Compact response
The default response is a compact envelope. It containsattention_items, attention_summary, grouped actionable signals, a
deterministic recommended_action when available, counts, delta, and
page. It omits full goals, standalone_kpis, standalone_initiatives,
assigned_issues, and project_context collections.
The serialized JSON response is bounded to 16,384 UTF-8 bytes and 25 signal
groups. The page object reports max_bytes, max_items,
returned_count, returned_bytes, has_more, next_cursor, and a terminal
ack_cursor. Continue with cursor=<next_cursor> until has_more is false.
Only the terminal page includes ack_cursor; after all pages are processed,
send it to:
next_cursor from the immediately
previous page; do not manufacture, skip, or replay a page cursor. Pass an acknowledged terminal cursor as
since=<ack-cursor> on a later compact read to receive only new, changed, or
escalated groups. Invalid cursors return 400. Stale page cursors and
unacknowledged since cursors return 409. If policy, authorization, or the
candidate set changes while paging, restart without the cursor after
409 heartbeat_cursor_stale. An expired acknowledged baseline returns a
fresh compact response with delta.reset_required: true.
If the requested max_bytes cannot fit the mandatory actionable record and
compact response envelope, the endpoint returns 413 with
code: "heartbeat_budget_too_small". It does not advance a page cursor or
terminal receipt. Retry with a larger max_bytes (up to 16,384) or omit the
parameter to use the default. Compact attention_items are bounded projections
with id, event_type, severity, title, resource_type, and
ack_endpoint; resource_id is included when present. Full mode retains the
richer attention fields.
Compact dependency signals group affected downstream issues under an
actionable upstream blocker and release condition. Expected waits are suppressed
for an unsatisfied dependency when the readable blocker is before its release
column and there is no active stall, threatened or overdue commitment, or
explicit deadline, gate, permission, or stale anomaly. An unowned backlog or
Todo blocker by itself is an ordinary wait and never alerts. Actionable groups
surface active stalls, threatened or overdue commitments, and explicit
anomalies; escalation metadata alone does not surface an expected wait. When
every dependency fact behind an initiative-target or stalled aggregate is an
expected wait, that aggregate is suppressed too. Groups can include a suggested_read with an
executable REST path, CLI command, or private MCP tool call.
Use ?view=full for the legacy full response. Full requests cannot combine
with since or cursor.
The public plugin MCP profile keeps the legacy full heartbeat shape and does
not expose compact paging or acknowledgement. Private MCP supports compact
heartbeat inputs and the atoll_ack_heartbeat tool.
Execution attention
Private REST, CLI, and MCP compact responses also include the separateexecution_attention projection:
resolved_unread until the requesting agent
acknowledges the receipt or completes the exact version-fenced
waiting -> running transition. Open requests remain in open. The existing
25-item and 16 KiB page limits apply across execution attention, notification
attention, and signals; resolved answers are ordered before open requests.
Heartbeat page acknowledgement only acknowledges the delivery snapshot and
does not consume an execution-attention receipt.
An agent acknowledges a resolved answer with:
409 for stale versions or key reuse with a different body, and never
resumes an execution. Public plugin MCP heartbeat output remains unchanged.
Per-agent policy management
The web app exposes these settings under Heartbeats. The management APIs require an authenticated human who can manage the target agent:GET returns the saved and effective policy, selectable projects, initiatives, and per-project board columns, plus stale selections. PUT atomically replaces the complete policy. DELETE removes the saved policy so the agent inherits the organization default, or the built-in behavior when none is set. Preview accepts { "policy": ... } for an unsaved draft or {} for the saved policy and composes the heartbeat as the target agent without persisting changes.
When access or entities change, saved_policy retains stale IDs so the real heartbeat and a {} saved preview fail closed instead of treating that dimension as All. effective_policy is the sanitized, editable form and stale_selections identifies what was removed from it. Saving that sanitized form explicitly removes the stale restrictions.
Organization default and bulk focus
Agents without a custom policy inherit the organization default. Precedence is the agent’s custom policy, then the organization default, then the built-in all-on heartbeat. No default row keeps the built-in behaviour. These endpoints require an authenticated human session; agent API keys receive403.
GETdefault is available to owners, admins, and members who can manage at least one agent.PUTandDELETErequire owner or admin.PUTaccepts only{ "sections": {...}, "signal_categories": {...} }; entity selections remain per agent. Responses returndefault_policy.source(organizationorbuilt_in), the switches,updated_at,updated_by, andcan_edit.- Bulk accepts
{ "action": "apply_focus", "agent_ids": [...], "sections": {...}, "signal_categories": {...} }or{ "action": "reset", "agent_ids": [...] }for 1 to 100 agents. Every agent must pass the per-agent manageability check; one failure rejects the whole request before any write.apply_focuskeeps each agent’s project, initiative, and column selections.resetdeletes custom policies so agents inherit the organization default. - The overview returns, for the caller’s manageable agents only,
heartbeat_status(receivingwithin 7 days,idle,never_woken, orno_projectswhen the agent has no effective project access),heartbeat_activity(last heartbeat, 24-hour deliveries, surfaced and acknowledged counts, and seven UTC-day surfaced totals), duplicate display names with a non-secretdisambiguator, totals, and the organization default.
Heartbeat focus narrows proactive signals only. It cannot grant project access, create initiative permissions, or create task-column permissions.
verification.completed item for an exact matched
repository, pull request, workflow run attempt, and head SHA. Its validated
verification object contains only bounded identifiers, the conclusion, a
canonical GitHub run URL, and next_action; it never contains raw payloads,
secrets, logs, or thread identifiers. The integration is disabled by default
and workflow processing remains observe-only unless an owner or admin enables
attention mode.
The public MCP heartbeat excludes verification.completed. Use the authorized
REST endpoint or atoll heartbeat --json for this private integration evidence.
An empty project, initiative, or column selection means All. Every signal has one stable category: task, initiative, KPI, or project. Disabled sections retain the response shape with empty collections; disabling attention empties both attention_items and its summary counts.
CLI equivalent:
Legacy full response shape
project_context includes ordered board columns for accessible projects relevant to the heartbeat, including optional column descriptions that teams use as stage criteria or agent guidance.
attention_items contains direct notifications that require the current member’s attention, including mentions, assignments, assignee comments, direct replies, and creator-visible status changes. Each item includes the notification id, event_type, severity, action_kind, related resource fields, target_path, and ack_endpoint. Comment items can include comment_id; a direct reply can additionally include reply_to_comment_id and the parent agent comment’s validated routing metadata (harness, thread/session ID, and optional host ID). If routing is absent, fetch the new reply through GET /comments/{comment_id} (or list the issue comments) and inspect its shallow reply_to_comment.source_metadata; this remains available when the parent was later soft-deleted. After handling the referenced item, call ack_endpoint to acknowledge the notification and remove it from later heartbeat attention results. attention_summary aggregates unread attention counts by type. Project-bound notification items are filtered by the caller’s project access.
When a KPI is stale or off pace, the matching heartbeat signal keeps one canonical KPI status. Its metadata.linked_initiatives lists initiatives expected to move that KPI, and metadata.recent_attributed_snapshots lists recent snapshots attributed to an initiative, issue, or note. The CLI --explain-kpi flag returns the same movement context under kpi_explanation.
recommended_action is a deterministic strategy-backed next action built from the heartbeat summary. Action types are create_work, start_work, escalate_blocker, refresh_metric, and investigate. The suggested_write object can prefill a new issue, issue status update, blocker comment, or KPI refresh request; an investigation can use operation: "none" when heartbeat lacks enough detail for a safe write. Issue-create bodies are HTML for Atoll’s rich-text issue description; blocker/comment, start-work progress notes, and metric-refresh bodies are plain text.
Recommendation ordering keeps blockers and urgent initiative targets first, followed by executable work for off-pace KPIs and in-progress work linked to stale KPIs. Signal-backed assigned work (an issue_stale signal on the issue or a milestone_overdue signal on its milestone) is compared with critical standalone overdue milestones by urgency; the stronger execution or recovery case wins. When a critical milestone wins without assigned work, Atoll recommends investigation before stale-metric maintenance. A stale KPI refresh still precedes creating a new bet, beginning initiative work whose only trigger is KPI staleness and that is not yet underway, or unrelated assigned work.
Agents should follow usage_guidance: prefer suggested_write.operation when it still matches the current board, preserve KPI/initiative/initiative-target/why-now/expected-impact/first-step/success-criteria evidence in any write, and avoid copying deferred busywork or unrelated assigned tasks into issue or comment payloads. When a start_work action uses suggested_write.operation: "issue.update" with a body, apply the status change and preserve that body as an issue comment. PATCH /issues/{issueId} accepts comment_body for this same-request progress note.
Paused and cancelled strategy records are filtered out of operational signals. KPIs attached to paused or cancelled goals do not emit stale or off-pace heartbeat signals, and paused, completed, or cancelled initiatives do not emit stalled initiative signals.
Signals
Severity values are
critical, warning, and info.
Gate target signals are stateful and do not use KPI pace language. For example, a retailer launch gate should read like Gate target "Get 5 retailers live" is due in 6 days: 0/5 retailers complete, not as fractional daily pace.
Agent guidance
Agents should:- Call heartbeat at the start of a run.
- Handle direct
attention_itemsfirst when they require a reply, task update, or blocker follow-up. - Call each handled item’s
ack_endpoint. - Sort remaining signals by severity and business leverage.
- Inspect the relevant issues, KPI, initiative, or milestone.
- Act through CLI or API.
- Comment and update records.
- Stop when the current unit is complete.
Task filter contract
HeartbeatPolicyInput.task_filters is optional. Omission preserves legacy task selection. When supplied, it is a strict object with all five fields:
due_within_days is null (off) or a nonnegative safe integer, with no product-specific maximum. recent_attempt_cooldown_hours is null (off) or a finite nonnegative number no greater than JavaScript’s safe integer limit. The booleans default to false; assignment scope defaults to assigned. The other scope value is assigned_or_unassigned_team. Unknown keys, negative windows, fractional due days, and nonfinite numbers return 400. Persisted filters are replaced atomically with the policy. Organization defaults contain switches only; bulk focus preserves task filters, and reset removes them.
Due dates and agent_not_before use the workspace date in its IANA timezone. Due selection includes overdue work and the exact window boundary, and excludes undated tasks. Assignment considers both the legacy assignee and every assignment link. Team expansion requires actual team membership, no assignees, and project access. Dependencies use existing release conditions and fail closed on incomplete or hidden facts. Cooldown reads this agent’s authoritative execution history; a newer task update restores eligibility. Active executions remain excluded.
An active task rule applies the existing project, initiative and task-column focus to all task candidate paths. Excluded issues cannot return through linked tasks or compact dependency groups. New eligible tasks use issue_actionable signals in both full and compact output. Direct attention, strategy/KPI health, permissions and runner admission retain their controls. With all rules disabled/default, legacy selection remains unchanged.
Preview returns a separate nullable evaluation object: evaluated, eligible, excluded, and primary_reason_counts. Reasons include missing_due_date, due_outside_window, not_before_date, not_assigned_or_team, column_not_selected, unresolved_dependency, active_execution, recent_attempt, and generic facts_unavailable. Each excluded task contributes once under its first deterministic reason. Counts cover scoped candidates, never the whole backlog. Preview returns delivery.persist=false and writes no delivery, telemetry or attention receipts.
Outbound heartbeat delivery
Outbound delivery is off by default. Open an agent from Heartbeats, then use Outbound delivery to select an existing automation webhook. A human must be able to manage both the agent and destination. Project destinations receive only work in that project, within the agent and manager’s current access. Subscription-only destinations are not selectable. Set an Evaluation interval in 15-minute steps and a separate Minimum wake interval in minutes. Checks use the existing maintenance schedule, so they are not exact-time alarms. Queued deliveries run through the webhook retry queue; a newly queued wake can wait until the next maintenance sweep. The default condition is New or changed eligible work. Any eligible work can repeat unchanged work after the minimum interval. Include critical direct attention is optional and off by default. KPI health, strategy signals, aggregate attention counts, and human execution answers do not trigger wakes. The saved heartbeat policy controls task scope and eligibility. A date threshold, released dependency, new assignment, changed priority or status, or completed attempt cooldown can make work newly actionable without a new issue edit. Due dates and due windows are calendar days in the workspace timezone; there is no hour-based task deadline. Active executions and completed or archived tasks do not qualify. Missing required dependency evidence excludes work. Credentials and private destination URLs never enter the heartbeat body. Save settings, then select Preview outbound decision to see whether Atoll would send now, its reason, qualifying items, next check, and cooldown end. Preview does not queue a request or change scheduling, receipts, or baselines. Test webhook deliberately queues an empty payload labeledtest: true.
It does not advance the normal wake baseline or minimum interval. Use
Delivery history and Refresh history to inspect checks, skips, attempts,
acceptance, retry-pending and failed states. Disable outbound delivery takes
effect before subsequent attempts. An HTTP request already in progress cannot
be recalled. Disabling or deleting an agent removes its outbound opt-in;
enabling an agent later requires explicit outbound opt-in again.
An HTTP 2xx response means accepted, not work completed. Outbound delivery
never changes issues, execution claims, notifications, human-attention receipts,
or inbound heartbeat acknowledgements. The accepted outbound baseline is
separate from the inbound since and ack_cursor state.
Each request uses event agent.heartbeat, schema version 1, and a stable
wakeId. Its compact items contain stable IDs, revisions, reasons, titles,
project scope and canonical Atoll links. Requests contain at most 25 items and
16 KiB; remaining changed work can appear on later checks. Transport is
at-least-once: a lost response can cause the same wake to arrive again.
Receivers must deduplicate wakeId (also the stable webhook delivery header ID).
Retries keep the original body and identity, use the existing signing and
private bearer configuration, and wait at least five minutes; the maintenance
cadence can delay them further. Agent, destination, configuration, policy,
permissions and current work are checked again before each attempt. Changed
or unavailable eligibility cancels that wake and leaves its baseline unaccepted.
Outbound management API
PUT accepts exactly these fields:
webhook_id is an existing authorized automation/both destination UUID or null;
enabling requires one. Evaluation minutes are positive 15-minute multiples;
minimum wake minutes are nonnegative. Both fit a PostgreSQL integer.
gate also accepts any_eligible_work. Missing or unknown fields return 400.
Preview/test take no configuration input; save a draft before using them.
The preview decision contains would_send, reason, items,
qualifying_count, truncated, fingerprint, accepted_state,
next_check_at and cooldown_end. Reasons are disabled, not_due,
no_eligible_work, unchanged, cooldown, pending,
destination_unavailable and ready.
An enabled agent needs heartbeat.manage_self for itself or
heartbeat.manage_others for an exact same-organization agent or all other
agents. Other excludes self. Both grants cover briefing policy and outbound
configuration; neither grants project access or destination creation. Current
caller and target access restrict settings and previews. A project destination
also needs the caller’s webhook.dispatch and both agents’ project access;
an organization destination needs webhook.organization_manage.
Missing, foreign and unauthorized machine targets return 404. An authorized
inactive target GET returns only identity and lifecycle state; writes, preview
and test return 409. Responses are private/no-store. Tests use the actual
initiator and an empty labeled payload. Authority is checked at write, queue and
retry boundaries. A request already in flight cannot be recalled. Existing
human management rules and ordinary inbound reads/acknowledgements remain.
Use typed CLI heartbeat policy and heartbeat outbound commands or the
full/private MCP management tools. Existing public auth context reports the
grants; new public heartbeat management tools remain excluded by the contract
freeze. Source delivery and package publication are separate.
Attention categories and event wakes
Optionalattention_categories is a complete boolean record:
{"assignment":true,"mention":true,"blocker":true,"execution":true}.
Omission enables every category; explicit null, partial records, unknown keys
and nonboolean values are invalid. sections.attention remains the master.
Per-agent policy, unsaved policy preview, organization defaults and bulk focus
use this same field. Reset inherits the organization default, then built-in
all-on behavior. Bulk focus keeps entity selections and task eligibility rules.
Assignment maps issue.assigned; mention maps mention.created and
comment.added (including direct replies); blocker maps issue.blocked,
issue.status_changed and unknown notification types; execution maps
verification.completed, human_attention.requested and requester execution
attention. Unknown types keep legacy visibility but have informational wake
semantics. Generated task/blocker signals keep their separate signal controls.
Full, compact and draft output filter before summaries and recommendations.
Compact notifications add category and wake_class. Summary counts retain
mentions, assignments and blocker events; total_unread counts all visible
notifications. Execution open/resolved summaries are separate.
Assigned work controls the task list. Assignment events remain independent.
An event for an out-of-window or deferred task is attention, never executable
work and never a task-based wake.
Outbound configuration adds optional include_informational_attention and
include_actionable_attention, both false when omitted. Existing
include_critical_attention remains false by default. Informational includes
assignments (even when notification severity is action_required), ordinary
comments, status updates and open execution waits. Actionable includes mentions,
direct replies, blockers, verification, human-attention notifications and
resolved execution answers. Critical severity uses the critical option.
All classes require the saved category filter and current authorized scope.
Execution answers require an explicit version-fenced resume; delivery does not
resume work. Other-agent machine management does not disclose private attention.
Each event has a stable key/revision independent of task titles, unrelated
execution edits, policy settings and check time. Acceptance records that exact
revision separately from notification read/acknowledgement. Events never repeat
after acceptance, including with any_eligible_work; that setting permits
repeated task wakes only. New event IDs or meaningful attention version/state
changes can qualify. Existing accepted critical notification revisions are
converted at migration to prevent rollout replay. Cooldown, pending locks,
bounded payloads, retry wake IDs, secure transport and attempt authorization
remain in force. The HTTP payload can contain attention, critical_attention
and execution_attention item kinds with category and wake_class, as well
as existing task items.
Policy preview uses its unsaved draft and sends nothing. Outbound preview uses
saved policy and saved delivery settings. Its bounded attention_evaluation
records category, class and not_selected, accepted or new_or_changed for
visible events. A new event still must pass schedule, destination, pending and
cooldown gates. Filtered or unauthorized events are absent from diagnostics.
CLI body-file writes and full/private MCP use the shared typed schemas. Public
management tools remain deferred during the public tool schema freeze; public
heartbeat keeps its legacy shape and existing private-event exclusions. Package
publication is a separate gate.
