///|

///|
/// Address of one interaction: owner-local id plus the runtime generation that
/// issued it. A ref from a previous generation is never accepted.
#derive(Eq, Debug)
pub(all) struct UiInteractionRef {
  owner : String
  request_id : String
  generation : Int32
}

///|
pub extend UiInteractionRef with Eq::{not_equal, equal}

///|
pub extend UiInteractionRef with Debug::{to_repr}

///|
/// What the user is allowed to answer.
#derive(Eq, Debug)
pub(all) enum UiInteractionBody {
  /// Free-form text, with an optional pre-fill.
  FreeText(default~ : String?)
  /// Yes/no confirmation.
  Confirmation
  /// Choose one option; `default` is the pre-selected index.
  Choice(options~ : Array[String], default~ : Int32?)
}

///|
pub extend UiInteractionBody with Eq::{not_equal, equal}

///|
pub extend UiInteractionBody with Debug::{to_repr}

///|
/// Coarse body category a connected host can answer. A host declares these in
/// `UiHostCapabilities`; an empty list means it can answer nothing.
#derive(Eq, Debug)
pub(all) enum UiInteractionKind {
  /// `FreeText` prompts.
  TextInput
  /// `Confirmation` prompts.
  YesNo
  /// `Choice` prompts.
  SingleChoice
}

///|
pub extend UiInteractionKind with Eq::{not_equal, equal}

///|
pub extend UiInteractionKind with Debug::{to_repr}

///|
/// The capability category of a body.
pub fn UiInteractionBody::kind(self : UiInteractionBody) -> UiInteractionKind {
  match self {
    FreeText(_) => TextInput
    Confirmation => YesNo
    Choice(..) => SingleChoice
  }
}

///|
/// The value the host answered with.
#derive(Eq, Debug)
pub(all) enum UiInteractionAnswer {
  Text(String)
  Yes
  No
  Choice(Int32)
}

///|
pub extend UiInteractionAnswer with Eq::{not_equal, equal}

///|
pub extend UiInteractionAnswer with Debug::{to_repr}

///|
pub extend UiInteractionAnswer with Show::{to_string, output}

///|
pub impl Show for UiInteractionAnswer with fn to_string(self) -> String {
  match self {
    Text(text) => "UiInteractionAnswer::Text(\"" + text + "\")"
    Yes => "UiInteractionAnswer::Yes"
    No => "UiInteractionAnswer::No"
    Choice(index) => "UiInteractionAnswer::Choice(" + index.to_string() + ")"
  }
}

///|
/// Owner-supplied request to open one question.
#derive(Eq, Debug)
pub(all) struct UiInteractionRequest {
  /// Owner-local id; reusing a live or retained id is `Duplicate`.
  request_id : String
  /// Where the question belongs.
  scope : UiResourceScope
  prompt : String
  body : UiInteractionBody
  title : String?
}

///|
pub extend UiInteractionRequest with Eq::{not_equal, equal}

///|
pub extend UiInteractionRequest with Debug::{to_repr}

///|
/// Construct a request with `AgentScope`, no title and no pre-fill.
pub fn UiInteractionRequest::new(
  request_id~ : String,
  prompt~ : String,
  body~ : UiInteractionBody,
  scope~ : UiResourceScope = AgentScope,
  title? : String,
) -> UiInteractionRequest {
  { request_id, scope, prompt, body, title, }
}

///|
/// One pending question as the host reads it.
#derive(Eq, Debug)
pub(all) struct UiInteractionSnapshot {
  interaction : UiInteractionRef
  scope : UiResourceScope
  prompt : String
  body : UiInteractionBody
  title : String?
}

///|
pub extend UiInteractionSnapshot with Eq::{not_equal, equal}

///|
pub extend UiInteractionSnapshot with Debug::{to_repr}

///|
/// Terminal state of one interaction. Every terminal path is named; none of
/// them is a silent removal from the pending set.
#derive(Eq, Debug)
pub(all) enum UiInteractionOutcome {
  /// A host answer settled the question.
  Answered(answer~ : UiInteractionAnswer)
  /// The user closed the prompt without choosing. `reason` is host-supplied
  /// and may be empty.
  Dismissed(reason~ : String)
  /// The owner withdrew its own pending question.
  Withdrawn
  /// The last waiting task was cancelled.
  WaitCancelled
  /// The Agent shut down (or a failed composition revoked the protocol) while
  /// the question was pending.
  Closed
}

///|
pub extend UiInteractionOutcome with Eq::{not_equal, equal}

///|
pub extend UiInteractionOutcome with Debug::{to_repr}

///|
pub extend UiInteractionOutcome with Show::{to_string, output}

///|
pub impl Show for UiInteractionOutcome with fn to_string(self) -> String {
  match self {
    Answered(answer~) =>
      "UiInteractionOutcome::Answered(" + answer.to_string() + ")"
    Dismissed(reason~) => "UiInteractionOutcome::Dismissed(\{reason})"
    Withdrawn => "UiInteractionOutcome::Withdrawn"
    WaitCancelled => "UiInteractionOutcome::WaitCancelled"
    Closed => "UiInteractionOutcome::Closed"
  }
}

///|
/// One lifecycle change of the interaction feed.
#derive(Eq, Debug)
pub(all) enum UiInteractionChange {
  /// The question became pending.
  Opened(snapshot~ : UiInteractionSnapshot)
  /// The question settled. `outcome` says how; the snapshot is no longer
  /// pending.
  Settled(
    owner~ : String,
    request_id~ : String,
    outcome~ : UiInteractionOutcome,
  )
}

///|
pub extend UiInteractionChange with Eq::{not_equal, equal}

///|
pub extend UiInteractionChange with Debug::{to_repr}

///|
/// Explicit failures of the interaction protocol.
#derive(Eq, Debug)
pub(all) enum UiInteractionError {
  /// The Agent shut down, or composition failed after this capability was
  /// delivered; capabilities are closed and pending questions are settled as
  /// `UiInteractionOutcome::Closed`.
  Closed
  /// No live or retained interaction for this owner/id at this generation.
  NotFound(owner~ : String, request_id~ : String)
  /// The owner already used this request id; the old question is live or still
  /// retained in the settled window.
  Duplicate(request_id~ : String)
  /// Structurally invalid request (empty id/prompt, bad body, forged owner).
  InvalidInput(reason~ : String)
  /// The answer does not fit the body the owner declared. The question stays
  /// pending, so the host can answer again.
  InvalidAnswer(reason~ : String)
  /// The question already ended another way; answering now changes nothing.
  AlreadySettled(outcome~ : UiInteractionOutcome)
  /// A repeated answer carries a different value than the accepted one.
  Conflict(reason~ : String)
  /// Too many pending questions; the request is refused, never dropped.
  PendingFull(limit~ : Int32)
  /// No connected host can handle this interaction. An explicit `open` stays
  /// pending for a later host; an `ask` that never created one consumed
  /// nothing.
  HostUnavailable(reason~ : String)
  /// The runtime already holds the maximum number of connected hosts.
  ConnectionsFull(limit~ : Int32)
  /// The user dismissed the prompt before an answer arrived.
  Dismissed(reason~ : String)
  /// The owner withdrew the question before an answer arrived.
  Withdrawn
}

///|
pub extend UiInteractionError with Eq::{not_equal, equal}

///|
pub extend UiInteractionError with Debug::{to_repr}

///|
pub extend UiInteractionError with Show::{to_string, output}

///|
pub impl Show for UiInteractionError with fn to_string(self) -> String {
  match self {
    Closed => "UiInteractionError::Closed"
    NotFound(owner~, request_id~) =>
      "UiInteractionError::NotFound(owner=\{owner}, request_id=\{request_id})"
    Duplicate(request_id~) => "UiInteractionError::Duplicate(\{request_id})"
    InvalidInput(reason~) => "UiInteractionError::InvalidInput(\{reason})"
    InvalidAnswer(reason~) => "UiInteractionError::InvalidAnswer(\{reason})"
    AlreadySettled(outcome~) =>
      "UiInteractionError::AlreadySettled(" + outcome.to_string() + ")"
    Conflict(reason~) => "UiInteractionError::Conflict(\{reason})"
    PendingFull(limit~) => "UiInteractionError::PendingFull(\{limit})"
    HostUnavailable(reason~) => "UiInteractionError::HostUnavailable(\{reason})"
    ConnectionsFull(limit~) => "UiInteractionError::ConnectionsFull(\{limit})"
    Dismissed(reason~) => "UiInteractionError::Dismissed(\{reason})"
    Withdrawn => "UiInteractionError::Withdrawn"
  }
}

///|
/// Host-side intent to answer one pending question.
#derive(Eq, Debug)
pub(all) struct UiInteractionAnswerRequest {
  interaction : UiInteractionRef
  answer : UiInteractionAnswer
}

///|
pub extend UiInteractionAnswerRequest with Eq::{not_equal, equal}

///|
pub extend UiInteractionAnswerRequest with Debug::{to_repr}

///|
/// Receipt of an accepted answer.
#derive(Eq, Debug)
pub(all) struct UiInteractionAnswerReceipt {
  interaction : UiInteractionRef
  answer : UiInteractionAnswer
  /// True when this question was already answered with the same value; the
  /// stored receipt is returned instead of settling a second time.
  replayed : Bool
}

///|
pub extend UiInteractionAnswerReceipt with Eq::{not_equal, equal}

///|
pub extend UiInteractionAnswerReceipt with Debug::{to_repr}

///|
/// Owner-bound interaction capability delivered through
/// `CompositionView::ui_interactions`.
pub struct UiInteractions {
  priv owner_ : String
  priv open_ : (UiInteractionRequest) -> Result[
    UiInteractionSnapshot,
    UiInteractionError,
  ]
  priv find_ : (String) -> Result[UiInteractionSnapshot, UiInteractionError]
  priv ask_ : (async (UiInteractionRequest) -> Result[
    UiInteractionAnswer,
    UiInteractionError,
  ] noraise)?
  priv wait_ : async (UiInteractionRef) -> Result[
    UiInteractionAnswer,
    UiInteractionError,
  ] noraise
  priv withdraw_ : (UiInteractionRef) -> Result[
    UiInteractionOutcome,
    UiInteractionError,
  ]
}

///|
/// The manifest id this capability is bound to.
pub fn UiInteractions::owner(self : UiInteractions) -> String {
  self.owner_
}

///|
/// Open one question and return its pending snapshot. Opening twice with the
/// same request id is `Duplicate`; open a new id instead of retrying silently.
pub fn UiInteractions::open(
  self : UiInteractions,
  request~ : UiInteractionRequest,
) -> Result[UiInteractionSnapshot, UiInteractionError] {
  (self.open_)(request)
}

///|
/// Find one of this owner's questions by its local `request_id`, whether it is
/// still pending or retained in the settled window. Unknown or evicted ids are
/// `NotFound`; a closed runtime is `Closed`.
pub fn UiInteractions::find(
  self : UiInteractions,
  request_id~ : String,
) -> Result[UiInteractionSnapshot, UiInteractionError] {
  (self.find_)(request_id)
}

///|
/// Wait for the terminal outcome of an already open question. Cancelling this
/// call settles the question as `WaitCancelled` instead of answering it `No`.
/// Without a connected host declaring the body kind the call returns
/// `HostUnavailable` immediately and leaves the question pending; a waiter
/// joining after the question settled still reads its terminal outcome.
pub async fn UiInteractions::wait(
  self : UiInteractions,
  interaction~ : UiInteractionRef,
) -> Result[UiInteractionAnswer, UiInteractionError] noraise {
  (self.wait_)(interaction)
}

///|
/// Open and wait in one call. When no connected host declares the body kind,
/// returns `HostUnavailable` without creating a pending question or consuming
/// the request id.
pub async fn UiInteractions::ask(
  self : UiInteractions,
  request~ : UiInteractionRequest,
) -> Result[UiInteractionAnswer, UiInteractionError] noraise {
  match self.ask_ {
    Some(callback) => callback(request)
    None =>
      Err(
        HostUnavailable(
          reason="this UiInteractions adapter does not negotiate host capabilities",
        ),
      )
  }
}

///|
/// Withdraw one pending question. Returns `Withdrawn` on success; the host sees
/// the same outcome on the feed and any waiting task resumes with `Withdrawn`.
pub fn UiInteractions::withdraw(
  self : UiInteractions,
  interaction~ : UiInteractionRef,
) -> Result[UiInteractionOutcome, UiInteractionError] {
  (self.withdraw_)(interaction)
}

///|
/// Framework construction hook. Omitting `ask` or `find` makes the
/// corresponding calls report `HostUnavailable`.
pub fn UiInteractions::from_callbacks(
  owner~ : String,
  open~ : (UiInteractionRequest) -> Result[
    UiInteractionSnapshot,
    UiInteractionError,
  ],
  wait~ : async (UiInteractionRef) -> Result[
    UiInteractionAnswer,
    UiInteractionError,
  ] noraise,
  withdraw~ : (UiInteractionRef) -> Result[
    UiInteractionOutcome,
    UiInteractionError,
  ],
  find? : (String) -> Result[UiInteractionSnapshot, UiInteractionError],
  ask? : async (UiInteractionRequest) -> Result[
    UiInteractionAnswer,
    UiInteractionError,
  ] noraise,
) -> UiInteractions {
  let find_callback = match find {
    Some(callback) => callback
    None =>
      fn(_request_id) {
        Err(
          HostUnavailable(
            reason="this UiInteractions adapter does not expose owner-bound lookup",
          ),
        )
      }
  }
  {
    owner_: owner,
    open_: open,
    find_: find_callback,
    ask_: ask,
    wait_: wait,
    withdraw_: withdraw,
  }
}