#13524: feat: conditional bootstrap file loading for heartbeat vs DM sessions
agents
stale
Cluster:
Cron Job Enhancements
## Problem
Workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, MEMORY.md) are injected into **every** agent run regardless of session type. This wastes tokens:
- **DM sessions** load HEARTBEAT.md (~300-1,500 tokens) which contains heartbeat poller instructions not needed during interactive conversations
- **Heartbeat runs** load SOUL.md, TOOLS.md, USER.md, MEMORY.md which are not needed for a periodic check
For users with multiple agents and detailed HEARTBEAT.md files, this adds up to **1,400+ wasted tokens per DM message**.
## Solution
Extend `filterBootstrapFilesForSession()` to support session-type-aware filtering:
- **Subagent sessions**: AGENTS.md + TOOLS.md (unchanged, existing behavior)
- **Heartbeat sessions**: HEARTBEAT.md + AGENTS.md + IDENTITY.md (new)
- **Normal DM sessions**: All files **except** HEARTBEAT.md (new)
The `isHeartbeat` flag is threaded from the auto-reply layer through the embedded runner to the bootstrap file resolver.
## Changes
- `workspace.ts`: Added `HEARTBEAT_BOOTSTRAP_ALLOWLIST`, `DM_BOOTSTRAP_EXCLUDELIST`, and `FilterBootstrapOptions` type. Extended `filterBootstrapFilesForSession()` with optional `opts` parameter.
- `bootstrap-files.ts`: Thread `isHeartbeat` through `resolveBootstrapFilesForRun` and `resolveBootstrapContextForRun`.
- `run/types.ts` + `run/params.ts`: Added `isHeartbeat?` to embedded run params.
- `run/attempt.ts` + `run.ts`: Pass `isHeartbeat` to bootstrap context resolver.
- `followup-runner.ts` + `agent-runner-execution.ts`: Pass `isHeartbeat` to embedded runner.
## Testing
- All existing tests pass (`workspace.test.ts`: 4/4, `bootstrap-files.test.ts`: 2/2)
- Backward compatible: the `opts` parameter is optional, existing behavior unchanged when not provided
## Related Issues
- #9157 (workspace file injection wastes 93.5% of token budget)
- #1594 (heartbeat cron jobs load full main session context)
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds session-type-aware bootstrap file filtering to reduce token waste: subagent runs continue to load a minimal allowlist, heartbeat runs load only HEARTBEAT.md + core identity/agent files, and normal DM sessions load everything except HEARTBEAT.md. The new `isHeartbeat` flag is threaded from the auto-reply layer through the embedded runner into the bootstrap resolver, which then calls the updated `filterBootstrapFilesForSession()`.
Main issue to address before merge: followup runs don’t register `isHeartbeat` in the agent run context, which can break downstream behavior that relies on `getAgentRunContext(runId)?.isHeartbeat` (notably webchat broadcast suppression for heartbeats).
<h3>Confidence Score: 3/5</h3>
- Not safe to merge until followup heartbeat runs are correctly classified.
- The bootstrap filtering and isHeartbeat threading are mostly consistent, but followup runs omit isHeartbeat when registering AgentRunContext, which breaks downstream heartbeat-specific behavior (e.g., suppressing heartbeat broadcasts).
- src/auto-reply/reply/followup-runner.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#9521: fix: restrict bootstrap files for cron agentTurn sessions
by ComputClaw · 2026-02-05
80.0%
#22277: fix: prevent heartbeat model override from bleeding into main session
by zhangjunmengyang · 2026-02-21
79.6%
#12786: fix: drop heartbeat runs that arrive while another run is active
by mcaxtr · 2026-02-09
78.7%
#9726: feat: add identityDir config for separate identity file location
by rickburn · 2026-02-05
78.5%
#16321: Fix #12767: suppress HEARTBEAT_OK leakage in Telegram DM replies
by tdjackey · 2026-02-14
77.5%
#3335: Fixes cron jobs
by hkirat · 2026-01-28
76.8%
#11647: fix(webchat): filter HEARTBEAT_OK messages from chat.history response
by liuxiaopai-ai · 2026-02-08
76.6%
#10644: feat: add runDuringHeartbeats option for memory flush (AI Assisted)
by tripphillips · 2026-02-06
76.4%
#9429: fix: skip session model override for heartbeat runs
by dbottme · 2026-02-05
76.4%
#21682: fix(heartbeat): propagate sessionKey in exec/hooks to fix async con...
by eviaaaaa · 2026-02-20
76.2%