Problem

Heartbeat runs on a fixed timer regardless of whether the user is currently in an active conversation with the agent. This causes several issues:

1. Interrupted conversations: The agent stops responding to the user and starts doing heartbeat work instead
2. Broken context: The conversation flow is disrupted
3. Wasted tokens: Heartbeat consumes tokens that should go to the active dialogue
4. Confusion: The user waits for a response while the agent is doing background tasks

Proposed Solution

Add a configuration option to skip heartbeat when there has been recent user activity:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        skipIfRecentActivity: true,  // new option
        recentActivityWindow: "5m", // skip if user message within this window
      },
    },
  },
}

Behavior

• When skipIfRecentActivity: true, check the timestamp of the last user message in the main session
• If the last user message is within recentActivityWindow (default: 5 minutes), skip this heartbeat tick
• The next scheduled heartbeat will run normally (unless there's still recent activity)
• This ensures heartbeats only run during genuine idle periods

Alternative Approaches

1. Queue-aware skip: If there's a pending user message in the queue, skip heartbeat
2. Defer instead of skip: Push the heartbeat back by N minutes instead of skipping entirely
3. Session state check: Skip if session is in "active conversation" state (could be determined by message frequency)

Use Case

I'm running an agent that uses heartbeats for background monitoring (inbox, calendar, etc.). When I'm actively chatting with my agent about something, the heartbeat fires and the agent goes off to check emails instead of responding to me. This breaks the conversation flow and is frustrating.

The heartbeat is valuable during idle periods, but counterproductive during active use.

Related to conversation context and user experience during active sessions.