pig

-module(pig@agent@step_result).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/pig/agent/step_result.gleam").
-export_type([step_result/1]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " Step result type for the sans-IO core.\n"
    "\n"
    " The outcome of a single state transition — what happened after\n"
    " processing a message. Carries the new state and optional effects.\n"
    "\n"
    " Three variants:\n"
    "   - `Done`      — the agent produced a final answer\n"
    "   - `Continue`  — the agent needs more work (inference, tools)\n"
    "   - `Failed`    — an unrecoverable error occurred\n"
).

-type step_result(IQH) :: {done,
        pig@agent@state:agent_state(),
        pig_protocol@message:message()} |
    {continue,
        pig@agent@state:agent_state(),
        list(pig@agent@effect:effect(IQH))} |
    {failed, pig@agent@state:agent_state(), pig_protocol@error:ai_error()}.