Executes one isolated agent run.

Each run is its own GenServer, started anonymously (no name registration) by BeamAgent.RunSupervisor, so many runs can be in flight concurrently and one crashing has no effect on the others — the crash is contained to this process and surfaces to the caller of BeamAgent.API.run/2 as a {:runner_crashed, reason} error, not a propagating exit.

start_link/1 accepts:

• :goal (required) — the natural-language goal for the run.
• :llm (required) — {module, opts}, where module implements BeamAgent.LLM.Client.
• :tools — %{atom() => module} of tools available to this run, each module implementing BeamAgent.Tools.Behaviour. Defaults to %{}.
• :guardrails — options consumed by BeamAgent.Guardrails.
• :verification — options consumed by BeamAgent.Verifier.

Call run/2 to kick off execution; the result arrives as {:agent_run_finished, pid, result} sent to the given caller, after which this process stops normally.

Verification, context, and guardrail telemetry

Verification emits [:beam_agent, :verification, :start | :stop | :exception] around the configured verifier invocation only. Events carry :run_id and a fresh :telemetry_span_context. Starts measure system and monotonic time; terminals measure monotonic time and duration, all in native units. Stops classify outcome and verification status; errors use :verification_failed (or :unexpected_result for malformed returns). Exceptions include only :kind and error_type: :exception, and are re-raised unchanged.

Context emits [:beam_agent, :context, :compressed] only for actual compression, with :before_count, :after_count, :compressed_messages, and :summary_chars measurements. :compression_failed reports :configured_max_messages and :minimum_messages, with error_type: :context_limit_too_small. If that limit blocks compression, the unsatisfied context guardrail also emits one rejection, with the current rendered message count as :observed and the configured cap as :limit.

Guardrail rejection emits [:beam_agent, :guardrail, :rejected] with numeric :observed and :limit measurements. Metadata identifies :guardrail (:max_iterations, :max_tool_calls, :max_context_messages, or :max_execution_time), :phase (:before_step, :before_tool, or :context), and :unit (:count or :millisecond). Successful checks stay silent.

All point events include system/monotonic timestamps, count: 1, and metadata containing :run_id and the current :iteration (zero before the first model call). No execution content or raw failure reasons are emitted. Standalone context, verifier, and guardrail calls remain uninstrumented.