Skip to main content

​
Herdr

Atomic includes a built-in Herdr reporter. In an eligible pane it reports agent, extension approval, and observed workflow activity using source custom:atomic and agent label atomic. No community extension is required.

​
Prerequisites and environment

The CLI contract is based on Herdr 0.8.2, protocol 20. Launch Atomic in a Herdr pane whose environment includes: The reporter captures these values on activation, not at module import. It runs only when the extension context has mode: "tui" and hasUI: true. Print, JSON, RPC, no-UI, workflow-stage, and subagent contexts never claim a pane merely because they inherited its environment. Missing prerequisites, disabled reporting, or ineligible contexts create no reporter timer, subprocess, or workflow observation lease.

​
States and reasons

The reporter uses agent_start, agent_settled, ui_prompt_start, ui_prompt_end, and the owning session’s observeWorkflowActivity stream. It does not infer execution from screen text or use agent_end as the idle boundary. Independent workflow execution keeps the pane working even after the parent agent settles or while another contribution waits for approval. Reasons are internal reducer values, not extra CLI fields. Missing workflow knowledge is never treated as an empty ready snapshot, so an unavailable provider can leave the last reported state unchanged until a ready snapshot arrives.

​
Opt out

Set this in global ~/.atomic/agent/settings.json or trusted project .atomic/settings.json, then reload or restart Atomic:
The default is true, subject to the environment and ownership gates. Project settings override global settings using the normal settings precedence.

​
Reporter conflicts

If the actually loaded extension paths contain herdr-atomic-reporter or the legacy Pi herdr-agent-state, the built-in reporter defers without claiming or observing. One unsupported diagnostic names the loaded reporter path. Merely having such a package on disk does not cause deferral. The selected community or legacy reporter determines workflow coverage in that mode; Atomic’s built-in aggregation is inactive.

​
Ownership, delivery, and privacy

One module-owned lease reports each pane. A successor retires the predecessor before reporting. Sequence numbers use a clock seed and a process-level high-water mark, increasing across extension reloads, runner replacement, and clock rollback within that process. Shutdown drains the current child and releases authority with a fresh sequence strictly greater than the last report sequence. Late predecessor callbacks cannot report or release a successor. The reporter invokes the CLI directly with an argument array, not a shell. It permits one child per pane at a time, keeps only the newest pending state, and uses a five-second timeout plus bounded output buffering. Transport errors produce bounded spawn_failed, timeout, or protocol_rejected diagnostics; obsolete ownership uses stale_owner. Errors do not become agent or workflow failures. Child stdout and stderr are never logged raw. Only the fixed messages in the table are sent. Prompt titles, tool arguments, provider error bodies, transcripts, and workflow outputs are not forwarded. The parent’s session ID and, when available, native absolute session path accompany reports until the first successful CLI delivery per claim, using --agent-session-id and --agent-session-path. Later reports in that claim omit these flags. This is not a once-per-claim attempt: after a transport failure, later activity retries that identity; no retry timer is added. Child sessions do not replace that identity.

​
Compatibility

The reporter is tested against Herdr 0.8.2 (protocol 20); that is the minimum supported release. The rows below record the observed CLI and server behaviour the reporter is built on, and how Atomic responds. Additional limits on this release:
  • Reporting is event-driven. This integration adds no reconnect polling or crash-cleanup guarantee.
  • Host-owned trust prompts are not covered by the extension prompt events. See #2873.
The full activity path, from a real workflow run through the host observation stream to the herdr CLI invocations, is covered by an integration test against a fake herdr executable that records argv. It checks the ordered working → blocked → working → idle reports and strictly increasing --seq values for a tool-only execution followed by a human-input prompt. The state table it exercises is in Workflow activity for extensions. Workflow publication is a separate integration from this reporter. It consumes the host workflow observation contract without importing workflow scheduler internals.