@callback act(action(), state()) :: {:ok, state()} | {:error, term(), state()}

Execute an action. Returns updated state.

@callback context_snapshot(state()) :: map()

Snapshot state for crash recovery.

@callback init(keyword()) :: {:ok, state()} | state()

Initialize agent state from options.

@callback observe(events(), state()) :: {:ok, observation(), state()}

Observe events and produce an observation map.

@callback on_resume(state()) :: {:ok, state()}

Called when pilot releases.

@callback on_takeover(state()) :: {:ok, state()}

Called when pilot takes over.

@callback receive_directive(directive(), state()) :: {:ok, state()} | {:defer, state()}

Handle a directive from the orchestrator or pilot.

@callback restore_context(map()) :: {:ok, state()} | :error

Restore state from a snapshot.

@callback think(observation(), state()) ::
  {:act, action(), state()} | {:wait, state()} | {:ask_pilot, term(), state()}

Decide what to do based on the observation.

Returns:

• {:act, action, new_state} -- execute an action
• {:wait, new_state} -- do nothing this tick
• {:ask_pilot, question, new_state} -- escalate to human