Add test/hk_agent_fsm_tests.erl

test/hk_agent_fsm_tests.erl

@@ -0,0 +1,84 @@
+%%%-------------------------------------------------------------------
+%%% @doc Covers: deterministic state transitions, authorization
+%%% boundaries, and loop-limit enforcement (the "DAG-like agent
+%%% workflows", "authorization boundaries", and "deterministic state
+%%% transitions" items from `<test>').
+%%% @end
+%%%-------------------------------------------------------------------
+-module(hk_agent_fsm_tests).
+-include_lib("eunit/include/eunit.hrl").
+
+setup() -> hk_test_helper:start_app().
+teardown(Ok) -> hk_test_helper:stop_app(Ok).
+
+agent_fixture_test_() ->
+    {setup, fun setup/0, fun teardown/1, fun(_) -> [
+        {"created -> ready -> planning -> ... deterministic transitions",
+         fun deterministic_transitions/0},
+        {"unauthorized tool call is rejected without reaching the browser",
+         fun unauthorized_call_rejected/0},
+        {"invalid arguments are rejected at the control-plane boundary",
+         fun invalid_arguments_rejected/0},
+        {"exceeding max_actions transitions the agent to failed",
+         fun limit_exceeded_fails_agent/0},
+        {"agent process crash does not affect an unrelated agent",
+         fun crash_isolation/0}
+    ] end}.
+
+deterministic_transitions() ->
+    AgentId = hk_id:new(<<"agent">>),
+    {ok, Pid} = hk_agent_fsm_sup:start_agent(#{agent_id => AgentId, capabilities => [read_page]}),
+    {ok, #{state := created}} = as_map(hk_agent_fsm:describe(Pid)),
+    ok = hk_agent_fsm:assign_objective(Pid, <<"test objective">>),
+    {ok, #{state := ready}} = as_map(hk_agent_fsm:describe(Pid)),
+    %% A tool call the agent lacks any browser session for still drives
+    %% the state machine through planning -> executing -> waiting ->
+    %% planning; it fails at the toolbox level (no such session), which
+    %% is a normal, observed action outcome, not a stuck state.
+    {error, _} = hk_agent_fsm:next_action(Pid, browser, read_page,
+                                            #{session_id => <<"missing">>, tab_id => <<"missing">>}),
+    {ok, #{state := planning, action_count := 1}} = as_map(hk_agent_fsm:describe(Pid)),
+    ok = hk_agent_fsm:complete(Pid, #{summary => <<"done">>}),
+    {ok, #{state := completed}} = as_map(hk_agent_fsm:describe(Pid)).
+
+unauthorized_call_rejected() ->
+    AgentId = hk_id:new(<<"agent">>),
+    {ok, Pid} = hk_agent_fsm_sup:start_agent(#{agent_id => AgentId, capabilities => [read_page]}),
+    ok = hk_agent_fsm:assign_objective(Pid, <<"obj">>),
+    Result = hk_agent_fsm:next_action(Pid, browser, click,
+                                        #{session_id => <<"s">>, tab_id => <<"t">>, selector => <<"#x">>}),
+    ?assertEqual({error, not_authorized}, Result),
+    %% Action count must not increase for a call that never reached the toolbox.
+    {ok, #{action_count := 0}} = as_map(hk_agent_fsm:describe(Pid)).
+
+invalid_arguments_rejected() ->
+    AgentId = hk_id:new(<<"agent">>),
+    {ok, Pid} = hk_agent_fsm_sup:start_agent(#{agent_id => AgentId, capabilities => [navigate]}),
+    ok = hk_agent_fsm:assign_objective(Pid, <<"obj">>),
+    Result = hk_agent_fsm:next_action(Pid, browser, navigate,
+                                        #{session_id => <<"s">>, tab_id => <<"t">>,
+                                          url => <<"javascript:evil()">>}),
+    ?assertMatch({error, {invalid_arguments, _}}, Result).
+
+limit_exceeded_fails_agent() ->
+    AgentId = hk_id:new(<<"agent">>),
+    {ok, Pid} = hk_agent_fsm_sup:start_agent(#{agent_id => AgentId, capabilities => [read_page],
+                                                 limits => #{max_actions => 0}}),
+    ok = hk_agent_fsm:assign_objective(Pid, <<"obj">>),
+    Result = hk_agent_fsm:next_action(Pid, browser, read_page, #{session_id => <<"s">>, tab_id => <<"t">>}),
+    ?assertMatch({error, {limit_exceeded, max_actions}}, Result),
+    {ok, #{state := failed, failure_reason := Reason}} = as_map(hk_agent_fsm:describe(Pid)),
+    ?assertMatch({limit_exceeded, max_actions}, Reason).
+
+crash_isolation() ->
+    {ok, PidA} = hk_agent_fsm_sup:start_agent(#{agent_id => hk_id:new(<<"agent">>), capabilities => []}),
+    {ok, PidB} = hk_agent_fsm_sup:start_agent(#{agent_id => hk_id:new(<<"agent">>), capabilities => []}),
+    Ref = monitor(process, PidA),
+    exit(PidA, kill),
+    receive {'DOWN', Ref, process, PidA, killed} -> ok after 2000 -> ?assert(false) end,
+    timer:sleep(100),
+    ?assert(is_process_alive(PidB)),
+    ?assert(is_process_alive(whereis(hk_agent_sup))),
+    ?assert(is_process_alive(whereis(hyperkitty_sup))).
+
+as_map({ok, Record}) -> {ok, hk_schema:to_map(Record)}.