feat(cron): continuable cron jobs — thread-preferred continuation with DM-mirror fallback

[victor-kyriazakos]

What & why

Cron deliveries today live only in the cron job's own isolated session. When a brief is delivered to a chat and the user replies ("start Task #2"), that reply lands on a target session with no record of the brief — the agent asks "what is Task #2?". This makes recurring conversational jobs (daily briefings, reminders that kick off follow-up work) a dead end.

This PR makes a cron job optionally continuable: the delivered result becomes a conversation the user can reply into, with the brief already in context. Opt-in, default OFF — the historical isolation guarantee is preserved unless a job (or an operator) turns it on.

Design: thread-preferred, with a DM-mirror fallback

The continuation surface is chosen by a single platform-capability fork, scoped to the job's origin conversation only:

Platform class	Behaviour
Thread-capable (Telegram topics, Discord / Slack threads)	A dedicated thread is opened for the job via the adapter's create_handoff_thread, the brief is routed into it, and the thread-keyed session is seeded so the user's in-thread reply continues with full context. Each continuable job gets its own scrollback, isolated from the parent channel.
DM-only (WhatsApp / Signal / SMS)	No thread primitive exists (create_handoff_thread returns None), so the brief is mirrored into the origin DM session — the DM itself is the continuation surface.

A None return from create_handoff_thread is the fallback signal, so there is one code path, not two features. This mirrors GatewayRunner._process_handoff's existing open-thread-or-fallback + seed pattern already used for CLI→platform handoffs.

Footprint (per AGENTS.md — expansive at the edges, conservative at the waist)

• No new core tool, no new model-tool schema surface.
• No new adapter method and no supports_threads flag — reuses the shipped per-platform create_handoff_thread; its None return is the capability probe.
• No provider-chain signature change — reaches the live SessionStore via the adapter's existing _session_store handle rather than threading a new param through the frozen CronScheduler.start() contract.
• No new HERMES_* env var — the behavioural setting is cron.mirror_delivery in config.yaml, overridable per-job via the cronjob tool's attach_to_session.
• Existing per-target delivery routing carries the new thread_id for free.

Net diff is +711 lines, additive only, across 5 files.

Invariants

• Origin-scoped only. Threading/mirroring fires only for the delivery target whose (platform, chat_id[, thread_id]) equals the job's origin. Fan-out / broadcast / home-channel-fallback targets are never threaded or mirrored — they are not a continuation of a conversation and may legitimately have no session.
• Cache- and alternation-safe. The brief is appended as an assistant turn at a turn boundary, never mid-loop, and never mutates the cached system prompt. A thread_seeded guard prevents a double-mirror after seeding.
• Conservative on ambiguity. The DM path reuses gateway/mirror.py's _find_session_id, which returns None (no-op) rather than guess when a chat has multiple participant sessions and none matches the origin sender — parity with interactive send_message. The thread path sidesteps this entirely: a fresh chat_type="thread" session is participant-shared by construction.
• Best-effort continuation. A mirror/seed failure never fails a delivery that already succeeded.

Config / surface

cron:
  # Make cron deliveries CONTINUABLE (default false). Per-job
  # attach_to_session overrides this.
  mirror_delivery: false

Per-job opt-in via the cronjob tool: attach_to_session: true.

Testing

• tests/cron/test_scheduler.py — 185 passed, including the new mirror/thread/continuable coverage: thread id returned on a thread platform; None on a DM platform; None without capability/loop; seed creates the thread session + mirrors; seed no-op on empty content; plus the origin-scoping suite (exact match; other-chat / other-platform / no-origin rejection; thread scoping; fan-out mirrors ONLY the origin target).
• Full tests/cron/ suite: 538 passed, 7 skipped; the 4 failures are pre-existing croniter-not-installed env failures (compute next_run from cron expressions), unrelated to this change and identical on untouched main.
• Syntax + imports clean, no new Pyright errors. Rebased cleanly onto current main.

Commits

• feat(cron): optional mirror of cron delivery into target chat session
• refactor(cron): scope delivery mirror to the origin conversation
• feat(cron): pass origin user_id to delivery mirror (send_message parity)
• feat(cron): thread-preferred continuable delivery (open a thread, mirror DM fallback)

[kshitijk4poor]

Great PR — well-structured, opt-in, origin-scoped, and the thread-preferred + DM-fallback design mirrors the existing handoff pattern. All reuse claims check out (create_handoff_thread, mirror_to_session, safe_schedule_threadsafe, SessionSource, _session_store). CI green, 22 new tests pass.

However, this re-introduces the exact alternation violation that #2313 deliberately removed.

Background — issue #2221 and commit 37a9979

Cron deliveries used to be mirrored into gateway sessions as assistant-role messages. This caused consecutive assistant messages that violate role alternation (issue #2221). Teknium fixed this in #2313 by removing the mirror injection entirely — "Instead of fixing the role, remove the mirror injection entirely. Cron outputs already live in their own cron session and don't belong in the interactive conversation history." The existing test test_no_mirror_to_session_call (test_scheduler.py:879) enforces this: "Cron deliveries should NOT mirror into the gateway session."

This PR re-introduces that mirror, gated behind cron.mirror_delivery / attach_to_session (default OFF). The gate means the existing test still passes (no opt-in = no mirror), but the design decision it enforces is reversed when the feature is enabled.

Why the alternation violation persists

mirror_to_session writes role="assistant" to SQLite via _append_to_sqlite (mirror.py:157), which only passes role and content to SessionDB.append_message — the mirror: True and mirror_source metadata is dropped at the SQLite boundary. The gateway loads replay history from SQLite (load_transcript → get_messages_as_conversation), so the msg.get("mirror") check at run.py:814 that would prefix the content with [Delivered from <source>] always returns False on replay. The mirror message is indistinguishable from a real assistant turn.

repair_message_sequence (agent_runtime_helpers.py:347) merges consecutive user messages but does NOT merge consecutive assistant messages. The Anthropic adapter has _merge_consecutive_roles (anthropic_adapter.py:2069) that handles this, but the OpenAI/OpenRouter path does not.

Cron fires on a schedule, so the mirror lands right after the agent's last assistant turn (the common idle state). The next user reply sees assistant(real) → assistant(mirror, unlabeled) → user(reply) — two consecutive assistants, no label distinguishing the mirror from a real response. This causes silent empty responses on strict-alternation providers, triggering the empty-retry loop. This is the exact pattern described in issue #2221.

Fix direction

If the continuable-cron feature is wanted, the mirror should write as role="user" with a [Cron delivery: <task name>] prefix instead of role="assistant". The sequence becomes assistant(real) → user(cron brief) → user(reply) — repair_message_sequence already merges consecutive user messages, so this is alternation-safe for all providers. This also preserves the [Delivered from cron] distinguishability that the SQLite metadata-drop currently loses. This would require either a new helper or extending mirror_to_session with a role parameter.

Second issue — thread_seeded=True suppresses fallback mirror when live delivery fails

thread_seeded is set to True immediately after _seed_cron_thread_session returns (scheduler.py:1177), before the live adapter delivery attempt. If the live adapter delivery fails and falls through to the standalone path (which succeeds), _maybe_mirror_cron_delivery is called with enabled=mirror_this_target and not thread_seeded → enabled=False. The brief is visible in the new thread but has no session transcript — the exact "what is Task #2?" amnesia this PR exists to prevent.

Fix: set thread_seeded only after successful delivery, or re-enable the mirror on fallback.

Minor nits

• Duplicate import: BasePlatformAdapter imported twice in _deliver_result — as _BPA (line 1080) and as BasePlatformAdapter (line 1085), 5 lines apart. Use one import.
• Missing user_id in seed mirror: _seed_cron_thread_session calls mirror_to_session without user_id (scheduler.py:571-576), but the session was created with user_id="system:cron". When multiple candidate sessions exist with distinct user_ids, _find_session_id returns None and the mirror silently fails. Low probability for fresh threads, but worth fixing.
• No docs update: website/docs/user-guide/features/cron.md should document mirror_delivery / attach_to_session.
• Excessive docstrings: Several new functions have 30-50 line docstrings describing mechanics rather than non-obvious WHY. Per the AGENTS.md rubric, keep only non-obvious WHY comments.

What looks good

• Config key properly registered in DEFAULT_CONFIG["cron"].
• No new tools, no toolset changes, no system prompt mutation, no hardcoded paths.
• All reused primitives exist on main and are used correctly.
• Default-off preserves existing behavior byte-for-byte.
• Origin-scoping is correct — fan-out targets are never mirrored.
• user_id passthrough mirrors the send_message pattern.
• Test coverage is thorough (gate precedence, mirror calls/no-ops, cold-start, origin-scoping, fan-out, thread creation, session seeding).

[victor-kyriazakos]

Thanks @kshitijk4poor — excellent catch, and you're right on every point. Verified against source + history before fixing.

On the core concern (the #2313 reversal): confirmed. mirror_to_session writes role="assistant", so the continuable-cron mirror re-introduced exactly the assistant→assistant alternation violation that 37a9979 removed for #2221 — and the mirror/mirror_source metadata is dropped at the _append_to_sqlite boundary, so the [Delivered from cron] label is lost on replay, as you traced.

To be explicit about intent: this PR is a deliberate, opt-in, default-OFF reversal of #2313's "cron output doesn't belong in interactive history" — but only for the reply-to-cron use case, and only when cron.mirror_delivery / attach_to_session is set. The historical isolation guarantee is byte-for-byte unchanged for everyone who doesn't opt in (which is why test_no_mirror_to_session_call still passes). The alternation mechanics, though, were an unintended regression — that part should never have come back, opt-in or not. Fixed by your suggested direction:

Fixes pushed (bc245f217):

1. Mirror as a labelled user turn, not assistant. mirror_to_session gains a role param (default "assistant" — the interactive send_message mirror is unchanged; that text is the agent speaking). The cron paths now pass role="user" with a [Cron delivery: <task name>] prefix. Sequence becomes assistant(real) → user(cron brief) → user(reply), which repair_message_sequence's consecutive-user merge collapses safely on all providers — and the prefix preserves the cron-provenance the dropped SQLite metadata would otherwise lose on replay. Exactly your proposed fix.
2. thread_seeded ordering. Now deferred until delivery into the new thread actually succeeds. Previously set pre-delivery, so an open-succeeds / deliver-fails case both stranded a seeded-but-unseen brief and suppressed the DM-fallback mirror — fixed.
3. Seed user_id. _seed_cron_thread_session now passes user_id="system:cron" so the mirror resolves the exact thread-keyed session it just created.
4. Duplicate import removed (BasePlatformAdapter imported once).
5. Docs added for cron.mirror_delivery / attach_to_session in website/docs/user-guide/features/cron.md.
6. Docstrings trimmed to non-obvious WHY per the rubric.
7. Test added asserting the cron mirror writes role="user" with the label prefix (regression guard for bug(gateway): cron job outputs injected as assistant role, breaking message alternation #2221/fix(cron): stop injecting cron outputs into gateway session history #2313).

204 cron+mirror tests pass.

One thing worth a maintainer eye beyond the mechanics: the principle of letting opt-in continuable cron land in interactive history is a product call that reverses half of #2313's rationale. The alternation half is now genuinely fixed (user-role); the "belongs in history at all" half is the deliberate, gated trade we're making for reply-to-cron. Flagging it explicitly so it's a conscious sign-off rather than something that slipped through on a clean role-fix.

[teknium1]

Merged via #52250. Your 5 commits were cherry-picked onto current main with your authorship preserved in git log (rebase-merge). Verified on main: tests 186/186 green, E2E (gate resolution + origin-scoping + mirror backward-compat) passed. Thanks for the clean, well-scoped feature — the thread-preferred / None-fallback design and the alternation fix-up were exactly right.