[Docs]: Clarify heartbeat/cron behavior with multi-agent workspaces

[supergeoff]

The documentation for the heartbeat and cron job system does not clearly explain the relationship between the global workspace heartbeat and multiple agent contexts (agents/<id>/).

What's unclear

Several points remain unclear:

1. Does the heartbeat have access to session history across agents? The docs state it runs in a named("heartbeat") internal session, but it's unclear what visibility it has into other agents' sessions or their conversation history.
2. Are system events cross-agent? When a background exec finishes in Agent A's session, does that event appear in the heartbeat's event queue? Is the event queue workspace-scoped or per-agent?
3. How can a cron job target a specific agent? When creating a job via the cron tool, can you specify which agent's context (e.g., agents/main/BOOT.md) the agent turn should use?
4. Are agents/<id>/BOOT.md and agents/<id>/HEARTBEAT.md supported? The docs mention workspace-level BOOT.md and HEARTBEAT.md, but it's unclear whether agent-level versions are honored or ignored. If per-agent heartbeats are not supported, this should be stated explicitly.
5. What context is injected into the heartbeat prompt? Does the heartbeat turn receive workspace context files (SOUL.md, MEMORY.md, TOOLS.md, etc.) in addition to HEARTBEAT.md? If so, from which directory — the global workspace or a specific agent?

Suggested improvement

Add a "Heartbeat & Agent Architecture" section to the scheduling docs that clarifies:

• Execution scope of the heartbeat (workspace-global vs. per-agent capability)
• Visibility: What is visible/invisible from the heartbeat (sessions, events, workspace files)
• Cron job targeting: How cron jobs interact with named agents when multiple agents exist
• Prompt context: What full context is assembled for a heartbeat turn (which files, from which directory)
• A diagram showing the relationship: heartbeat → agents → sessions → system events queue

Additional context

In a multi-agent configuration (multiple agents/<id>/ directories), it's unclear whether the heartbeat can consolidate memory or perform actions scoped to a specific agent, or whether it operates purely at the global workspace level. For example, if using Honcho as a memory system, can the heartbeat create/update conclusions for a specific agent's peers, or is that outside its scope?

[Cstewart-HC]

I'll dive into this because I need a bit of clarification myself.

[Cstewart-HC]

Source-Grounded Answers

Q1: Does the heartbeat have access to session history across agents?

No. The heartbeat runs in a single named session with key cron:heartbeat (hardcoded in prepare_core.rs:652-654):

moltis_cron::types::SessionTarget::Named(name) => format!("cron:{name}")

SessionTarget::Named("heartbeat") always resolves to cron:heartbeat. Named sessions persist across runs but are isolated from each other — the heartbeat sees only its own conversation history from prior turns.

Q2: Are system events cross-agent?

Yes — the events queue is workspace-global, not per-agent.

A single SystemEventsQueue (Arc) is created in prepare_core.rs:610 and shared with:

1. The exec completion callback (post_state.rs:590-598) — any exec completion in any session enqueues to this queue
2. The on_agent_turn callback (prepare_core.rs:677-678) — drains the queue on heartbeat turns and prepends events to the prompt via build_event_enriched_prompt()

The queue is bounded to 20 events (MAX_EVENTS = 20, system_events.rs:16) with consecutive-duplicate dedup (system_events.rs:43). One queue for the entire gateway.

Q3: Can a cron job target a specific agent context?

Not directly. AgentTurnRequest (service.rs:108-117) has no agent_id field:

pub struct AgentTurnRequest {
    pub message: String,
    pub model: Option<String>,
    pub timeout_secs: Option<u64>,
    pub deliver: bool,
    pub channel: Option<String>,
    pub to: Option<String>,
    pub session_target: SessionTarget,
    pub sandbox: CronSandboxConfig,
}

The on_agent_turn callback in prepare_core.rs:615-762 constructs params with only text and _session_key. While send_sync (chat_impl.rs:69-73) can read agent_id from params, the callback never passes it.

resolve_prompt_agent_id (prompt.rs:78-88) defaults to "main" when no agent_id is set on the session, so all cron agent turns use the main agent persona.

Q4: Are agents/<id>/BOOT.md and agents/<id>/HEARTBEAT.md supported?

agents/<id>/BOOT.md — Yes. load_boot_md_for_agent(agent_id) exists at workspace.rs:257-260:

pub fn load_boot_md_for_agent(agent_id: &str) -> Option<String> {
    let agent_path = agent_workspace_dir(agent_id).join("BOOT.md");
    load_workspace_markdown(agent_path).or_else(load_boot_md)
}

It loads agents/<id>/BOOT.md with root fallback. Called from chat/src/prompt.rs:128 in persona assembly. The heartbeat does not use a specific agent_id, so it gets the default "main" agent BOOT.md (or root fallback).

agents/<id>/HEARTBEAT.md — No. load_heartbeat_md() (workspace.rs:285-287) reads exclusively from the root:

pub fn load_heartbeat_md() -> Option<String> {
    load_workspace_markdown(heartbeat_path())  // data_dir/HEARTBEAT.md
}

No per-agent HEARTBEAT.md variant exists.

Q5: What context is injected into the heartbeat prompt?

The heartbeat turn assembles context from the default ("main") agent workspace:

1. Heartbeat prompt — resolved by resolve_heartbeat_prompt() (heartbeat.rs:161-169) with precedence: config heartbeat.prompt → HEARTBEAT.md (root only) → built-in default
2. System events — drained from the global SystemEventsQueue, prepended to the prompt via build_event_enriched_prompt() (only if events exist, prepare_core.rs:677-687)
3. System prompt — assembled via resolve_prompt_agent_id() → defaults to "main" agent. Loads that agent identity, SOUL, MEMORY, AGENTS.md, TOOLS.md, project context, skills, and tool registry
4. Session history — the cron:heartbeat named session own conversation history (prior turns)

In summary: the heartbeat sees the main agent full system prompt + global system events + its own session history. It cannot be scoped to a specific agent through configuration alone.

[supergeoff]

Thx. Much appreciated!

[Cstewart-HC]

@supergeoff You are welcome, if you are satisfied with the answer please close the issue, help keep this place clean!

[penso]

@Cstewart-HC maybe this response should be in the documentation.