Migration Guide

View Source

This guide covers behavior and compatibility changes introduced while hardening jido_behaviortree for production use.

Runtime and Dependency Baseline

  • Minimum Elixir version is now 1.18.
  • Core runtime dependencies now target stable Jido 2.0.x releases.

Behavior Changes

Skill.run/3 failure semantics

Skill.run/3 now treats tree :failure as an execution failure.

  • Previous behavior: :failure returned {:ok, blackboard}.
  • New behavior: :failure returns {:error, reason}.

Timeouts and execution errors are also consistently returned as {:error, reason}.

Auto mode execution

Auto mode no longer sleeps for the full timeout window unconditionally. It now polls for terminal status and exits early on :success or :failure.

Blackboard propagation from SetBlackboard

SetBlackboard updates are now threaded through context-aware ticking and persist in Agent blackboard state.

Action error semantics in context mode

Action.tick_with_context/2 now returns error statuses consistent with tick/2. It no longer silently downgrades action errors to :failure.

Strategy snapshot status normalization

Jido.Agent.Strategy.BehaviorTree now normalizes non-atom tree error statuses to snapshot-compatible :failure, while preserving detailed error data in snapshot.details.error.

Telemetry Namespace

Telemetry events are under the [:jido, :bt, ...] namespace, including agent tick events.

  1. Update any call sites that assumed Skill.run/3 returns {:ok, ...} on tree failure.
  2. Verify monitors/alerts consuming telemetry event names use [:jido, :bt, ...].
  3. Re-run integration tests around action failure handling and blackboard persistence.