feat(cron): append deliveries to session context

[kovyrin]

What does this PR do?

Adds an opt-in way for cron deliveries to become part of the target chat's session context.

Cron jobs can now set append_to_session per job, or inherit a new global default cron.append_deliveries_to_session. After a successful delivery, the scheduler mirrors the raw delivered content into the matching target session so follow-up replies in that same chat or topic can refer to the cron message naturally.

Wrapped cron deliveries now reflect the effective behavior. When session mirroring is enabled, the wrapper explicitly says follow-up replies in that chat can refer to the message instead of implying the agent cannot see it.

The implementation reuses the existing gateway.mirror.mirror_to_session() path instead of inventing a cron-specific context cache. Session freshness updates and sessions-index persistence now live in gateway.session, so mirrored cron deliveries also refresh the matched session's updated_at without leaving low-level sessions.json writes inside gateway.mirror.

Related Issue

N/A

Related upstream context:

• Similar feature area: feat: conversational cron delivery — inject scheduled output into agent session #5659
• This PR keeps the implementation opt-in, per-job controllable, and based on the existing delivery mirror path.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Add append_to_session to cron job creation/update/listing, job storage, and the API server cron endpoints.
• Add global config support via cron.append_deliveries_to_session, document it in cli-config.yaml.example, and bump the config schema version.
• Mirror successful cron deliveries into the matching target session when the effective setting resolves true; per-job overrides global, raw content is mirrored instead of the cron wrapper, and the matched session updated_at is refreshed through gateway.session.
• Update wrapped cron delivery text so mirrored deliveries clearly tell the user that follow-up replies in the same chat can refer to the delivered message.
• Update user and developer cron docs plus troubleshooting guidance for the new follow-up-context behavior.
• Add coverage across cron scheduler behavior, cron job storage/tooling, gateway mirroring/session freshness, API server job endpoints, and CLI init/config loading.

How to Test

1. Create a cron job that delivers back to the current Telegram chat/topic with append_to_session=true, let it fire, then reply in that same chat with a follow-up like add that to my calendar.
2. Set cron.append_deliveries_to_session: true in ~/.hermes/config.yaml, verify jobs inherit the behavior by default, then set append_to_session=false on a noisy job and confirm it no longer appends into session context.
3. With cron.wrap_response: true, verify that mirrored deliveries say Follow-up replies in this chat can refer to this message. rather than implying the delivered content is detached from session context.
4. Run:

source .venv/bin/activate
python -m pytest tests/gateway/test_mirror.py tests/gateway/test_session.py tests/cron/test_scheduler.py tests/cron/test_jobs.py tests/tools/test_cronjob_tools.py tests/gateway/test_api_server_jobs.py tests/hermes_cli/test_cron.py tests/cli/test_cli_init.py -q

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Targeted test result:

• python -m pytest tests/gateway/test_mirror.py tests/gateway/test_session.py tests/cron/test_scheduler.py tests/cron/test_jobs.py tests/tools/test_cronjob_tools.py tests/gateway/test_api_server_jobs.py tests/hermes_cli/test_cron.py tests/cli/test_cli_init.py -q → 294 passed, 37 warnings

[huangrichao2020]

I like this shape: opt-in, uses the existing mirror path, and stores the delivered message instead of pretending the cron agent's scratch context belongs in the live chat.

The detail I would watch is the "same thing the user saw" invariant. If the wrapper says the agent cannot see the message while append_to_session is on, or if the mirrored content differs from the delivered content, users still end up debugging memory rather than using the feature. It looks like this PR already updates the wrapper language, which is important.

A small acceptance test worth keeping around: enable append_to_session for a cron that delivers into a gateway chat, deliver a report, then send a normal follow-up in that chat and verify session context includes the delivered report with the job id/output pointer, not the whole cron transcript.

[djangonavarro220]

Strong +1 for this.

This solves a real Telegram/forum-topic UX problem: scheduled cron outputs are delivered into a topic, then the user replies naturally (“this one”, “the last cron”, “buy it”, “why did you pick that?”), but the live agent has no context because the cron delivery is isolated.

The important constraints for me:

• opt-in per job / per topic, not global by default
• mirror exactly what the user saw, not the whole cron transcript
• preserve Telegram thread/topic targeting
• avoid the old bug(gateway): cron job outputs injected as assistant role, breaking message alternation #2221 assistant/assistant alternation bug
• include job_id/output pointer so the agent can recover full details if needed

I would use this immediately for shopping/watch crons and content-publishing crons where follow-up conversation is expected.

[teknium1]

Thanks for the opt-in design and for identifying the follow-up-context UX.

Problems

• Current main already implements this behavior via cron.mirror_delivery and per-job attach_to_session (cron/scheduler.py:583-612, introduced by 1b181724fae7799cf45dec3aca03ac44063175e7).
• The proposed mirror path would retain an assistant-role transcript entry. Current gateway/mirror.py:40-49 requires out-of-band cron briefs to use role="user"; b177d4ee4 fixed the resulting assistant→assistant alternation failure and tests/cron/test_scheduler.py:4155-4174 covers it.
• Current main also limits continuations to the origin chat/topic (cron/scheduler.py:615-645), rather than mirroring arbitrary successful fan-out targets.

Suggested changes

• Please salvage only the stale developer-doc corrections in website/docs/developer-guide/cron-internals.md:272 and website/docs/developer-guide/gateway-internals.md:199, rewritten for the shipped attach_to_session / cron.mirror_delivery contract. The current user guide documents that contract at website/docs/user-guide/features/cron.md:301-332.

Automated hermes-sweeper review.

[dellarb]

Big support here thought my agent was mad until i realised it doesn't have the same context I do.