feat: make StopReason a typed enum per ACP spec (#575)

Author: BlueHotDog

.changeset/stopreason-typed-enum.md

@@ -0,0 +1,6 @@
+---
+"@frontman/frontman-protocol": minor
+"@frontman/client": patch
+---
+
+Make StopReason a typed enum per ACP spec instead of a raw string. Defines the 5 ACP-specified values (end_turn, max_tokens, max_turn_requests, refusal, cancelled) as a closed variant type in the protocol layer, with corresponding Elixir module attributes and guard clauses on the server side.

apps/frontman_server/lib/agent_client_protocol.ex

@@ -39,11 +39,32 @@ defmodule AgentClientProtocol do
 
   @plan_statuses [@plan_status_pending, @plan_status_in_progress, @plan_status_completed]
 
+  # Stop reason constants — the single source of truth for ACP wire values.
+  @stop_reason_end_turn "end_turn"
+  @stop_reason_max_tokens "max_tokens"
+  @stop_reason_max_turn_requests "max_turn_requests"
+  @stop_reason_refusal "refusal"
+  @stop_reason_cancelled "cancelled"
+
+  @stop_reasons [
+    @stop_reason_end_turn,
+    @stop_reason_max_tokens,
+    @stop_reason_max_turn_requests,
+    @stop_reason_refusal,
+    @stop_reason_cancelled
+  ]
+
   def tool_call_status_pending, do: @tool_call_status_pending
   def tool_call_status_in_progress, do: @tool_call_status_in_progress
   def tool_call_status_completed, do: @tool_call_status_completed
   def tool_call_status_failed, do: @tool_call_status_failed
 
+  def stop_reason_end_turn, do: @stop_reason_end_turn
+  def stop_reason_max_tokens, do: @stop_reason_max_tokens
+  def stop_reason_max_turn_requests, do: @stop_reason_max_turn_requests
+  def stop_reason_refusal, do: @stop_reason_refusal
+  def stop_reason_cancelled, do: @stop_reason_cancelled
+
   def protocol_version, do: @protocol_version
 
   def agent_info do
@@ -115,7 +136,7 @@ defmodule AgentClientProtocol do
   @doc """
   Builds a session/prompt response with stop reason.
   """
-  def build_prompt_result(stop_reason) do
+  def build_prompt_result(stop_reason) when stop_reason in @stop_reasons do
     %{"stopReason" => stop_reason}
   end
 

apps/frontman_server/lib/frontman_server_web/channels/task_channel.ex

@@ -491,7 +491,9 @@ defmodule FrontmanServerWeb.TaskChannel do
         {:noreply, socket}
 
       id ->
-        response = JsonRpc.success_response(id, ACP.build_prompt_result("end_turn"))
+        response =
+          JsonRpc.success_response(id, ACP.build_prompt_result(ACP.stop_reason_end_turn()))
+
         Logger.info("Pushing prompt response with id=#{id}")
         push(socket, "acp:message", response)
 
@@ -510,7 +512,9 @@ defmodule FrontmanServerWeb.TaskChannel do
         {:noreply, socket}
 
       id ->
-        response = JsonRpc.success_response(id, ACP.build_prompt_result("cancelled"))
+        response =
+          JsonRpc.success_response(id, ACP.build_prompt_result(ACP.stop_reason_cancelled()))
+
         push(socket, "acp:message", response)
         socket = assign(socket, :pending_prompt_id, nil)
         {:noreply, socket}

apps/frontman_server/test/protocols/acp_contract_test.exs

@@ -19,7 +19,9 @@ defmodule FrontmanServer.Protocols.AcpContractTest do
 
   describe "AgentClientProtocol.build_prompt_result/1" do
     test "validates against acp/promptResult schema" do
-      payload = AgentClientProtocol.build_prompt_result("completed")
+      payload =
+        AgentClientProtocol.build_prompt_result(AgentClientProtocol.stop_reason_end_turn())
+
       ProtocolSchema.validate!(payload, "acp/promptResult")
     end
   end

libs/client/src/state/Client__State__StateReducer.res

@@ -581,8 +581,7 @@ let sendMessageToAPIImpl = (
         // reopening a Completed message as Streaming permanently.
         Client__TextDeltaBuffer.flush()
         switch result {
-        | Ok({stopReason})
-          if stopReason == "cancelled" => // CancelTurn already cleaned up state - don't dispatch TurnCompleted
+        | Ok({stopReason: Cancelled}) => // CancelTurn already cleaned up state - don't dispatch TurnCompleted
           ()
         | Ok(_) => dispatch(TaskAction({target: ForTask(taskId), action: TurnCompleted}))
         | Error(_) => dispatch(TaskAction({target: ForTask(taskId), action: TurnCompleted}))

libs/frontman-protocol/schemas/acp/promptResult.json

@@ -2,7 +2,13 @@
   "type": "object",
   "properties": {
     "stopReason": {
-      "type": "string"
+      "enum": [
+        "end_turn",
+        "max_tokens",
+        "max_turn_requests",
+        "refusal",
+        "cancelled"
+      ]
     }
   },
   "additionalProperties": true,

libs/frontman-protocol/src/FrontmanProtocol__ACP.res

@@ -296,13 +296,31 @@ let toolCallStatusSchema = S.union([
   S.literal(Failed),
 ])
 
+// Stop reason (per ACP spec)
+type stopReason =
+  | @as("end_turn") EndTurn
+  | @as("max_tokens") MaxTokens
+  | @as("max_turn_requests") MaxTurnRequests
+  | @as("refusal") Refusal
+  | @as("cancelled") Cancelled
+
+let stopReasonSchema = S.union([
+  S.literal(EndTurn),
+  S.literal(MaxTokens),
+  S.literal(MaxTurnRequests),
+  S.literal(Refusal),
+  S.literal(Cancelled),
+])
+
 // session/prompt result
-@schema
 type promptResult = {
-  @as("stopReason")
-  stopReason: string,
+  stopReason: stopReason,
 }
 
+let promptResultSchema = S.object(s => {
+  stopReason: s.field("stopReason", stopReasonSchema),
+})
+
 // Plan entry priority (per ACP spec)
 type planEntryPriority =
   | @as("high") High