///|

///|
/// Where a resource belongs.
#derive(Eq, Debug)
pub(all) enum UiResourceScope {
  /// The owning Agent instance.
  AgentScope
  /// A conversation/session id (turn-independent).
  SessionScope(id~ : String)
  /// One admitted operation, e.g. a single user turn.
  OperationScope(id~ : String)
  /// One tool call inside an operation.
  ToolCallScope(id~ : String)
}

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

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

///|
/// Reclamation promise of a published resource.
#derive(Eq, Debug)
pub(all) enum UiResourceLifetime {
  /// Lives until the owner withdraws it or the Agent shuts down.
  OwnerBound
  /// Reclaimed when the owning session ends (not implemented yet).
  SessionBound
  /// Reclaimed when the operation that created it settles.
  OperationBound
}

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

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

///|
/// Kind of a resource: namespace, name and schema version. Framework kinds
/// live in the reserved `posoco` namespace; a custom kind must use the
/// publisher's own namespace.
#derive(Eq, Debug)
pub(all) struct UiResourceKind {
  namespace_ : String
  name : String
  schema_version : Int32
}

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

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

///|
/// Construct a framework (`posoco`) kind.
pub fn UiResourceKind::standard(name~ : String) -> UiResourceKind {
  { namespace_: "posoco", name, schema_version: 1, }
}

///|
/// Construct a custom namespaced kind. `schema_version` must be positive.
pub fn UiResourceKind::custom(
  namespace_~ : String,
  name~ : String,
  schema_version~ : Int32 = 1,
) -> UiResourceKind {
  { namespace_, name, schema_version, }
}

///|
/// Structured body of a resource. Standard shapes cover the common cases; a
/// kind with no standard shape carries a namespaced `Custom` payload that the
/// host renders with its generic fallback.
#derive(Eq, Debug)
pub(all) enum UiResourceBody {
  Text(String)
  Lines(Array[String])
  KeyValue(Array[(String, String)])
  Entries(Array[UiEntry])
  Progress(Double)
  Markdown(String)
  /// Namespaced, versioned payload. The kind's namespace must not be the
  /// reserved `posoco` one.
  Custom(Json)
}

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

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

///|
/// Payload shape an action accepts.
#derive(Eq, Debug)
pub(all) enum UiActionPayloadKind {
  /// The action carries no payload; supplying one is invalid input.
  NoPayload
  /// The action carries a JSON value.
  JsonPayload
}

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

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

///|
/// One user-invokable action the resource declares.
#derive(Eq, Debug)
pub(all) struct UiActionSpec {
  id : String
  label : String
  payload : UiActionPayloadKind
}

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

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

///|
/// Owner-local address of one resource, bound to the runtime generation that
/// issued it. A ref from a previous runtime generation is never accepted.
#derive(Eq, Debug)
pub(all) struct UiResourceRef {
  owner : String
  key : String
  generation : Int32
}

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

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

///|
/// Full replacement payload for `publish` / `replace`.
#derive(Eq, Debug)
pub(all) struct UiResourceDraft {
  key : String
  kind : UiResourceKind
  scope : UiResourceScope
  lifetime : UiResourceLifetime
  title : String?
  body : UiResourceBody
  actions : Array[UiActionSpec]
}

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

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

///|
/// Construct a draft with the common defaults: `AgentScope`, `OwnerBound`, no
/// title and no actions.
pub fn UiResourceDraft::new(
  key~ : String,
  kind~ : UiResourceKind,
  body~ : UiResourceBody,
  scope~ : UiResourceScope = AgentScope,
  lifetime~ : UiResourceLifetime = OwnerBound,
  title? : String,
  actions~ : Array[UiActionSpec] = [],
) -> UiResourceDraft {
  { key, kind, scope, lifetime, title, body, actions, }
}

///|
/// Immutable copy of one accepted resource revision, as read through the host
/// feed. Replacing a resource bumps `revision` and keeps the same ref.
#derive(Eq, Debug)
pub(all) struct UiResourceSnapshot {
  resource : UiResourceRef
  revision : Int32
  kind : UiResourceKind
  scope : UiResourceScope
  lifetime : UiResourceLifetime
  title : String?
  body : UiResourceBody
  actions : Array[UiActionSpec]
}

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

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

///|
/// Lifecycle change of one resource in the host feed.
#derive(Eq, Debug)
pub(all) enum UiResourceChange {
  /// The resource did not exist before this revision.
  Published(snapshot~ : UiResourceSnapshot)
  /// Full replacement of an existing resource; the resource did not move.
  Replaced(snapshot~ : UiResourceSnapshot)
  /// The resource is no longer valid: withdrawn by the owner, or reclaimed by
  /// operation settlement. `revision` is the last live revision.
  Withdrawn(owner~ : String, key~ : String, revision~ : Int32)
}

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

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

///|
/// Explicit, non-silent outcomes of the resource protocol.
#derive(Eq, Debug)
pub(all) enum UiResourceError {
  /// The Agent shut down, or composition failed after this capability was
  /// delivered; capabilities are closed and the feed is over.
  Closed
  /// The runtime does not implement the requested behavior yet.
  Unsupported(feature~ : String)
  /// No live resource for this owner/key at the current generation.
  NotFound(owner~ : String, key~ : String)
  /// The caller's expected revision is not the live one.
  StaleRevision(expected~ : Int32, actual~ : Int32)
  /// Structurally invalid input (draft, action, payload, forged owner).
  InvalidInput(reason~ : String)
  /// The request id is already bound to a different action request.
  Conflict(reason~ : String)
  /// The same request id is currently being handled; retry after it settles.
  InProgress(request_id~ : String)
  /// The owner's action handler failed, raised, or is not installed.
  HandlerFailed(detail~ : String)
  /// The change cursor is out of the runtime's bounded window or generation.
  SnapshotRequired(reason~ : String)
}

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

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

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

///|
pub impl Show for UiResourceError with fn to_string(self : UiResourceError) -> String {
  match self {
    Closed => "UiResourceError::Closed"
    Unsupported(feature~) => "UiResourceError::Unsupported(\{feature})"
    NotFound(owner~, key~) =>
      "UiResourceError::NotFound(owner=\{owner}, key=\{key})"
    StaleRevision(expected~, actual~) =>
      "UiResourceError::StaleRevision(expected=\{expected}, actual=\{actual})"
    InvalidInput(reason~) => "UiResourceError::InvalidInput(\{reason})"
    Conflict(reason~) => "UiResourceError::Conflict(\{reason})"
    InProgress(request_id~) => "UiResourceError::InProgress(\{request_id})"
    HandlerFailed(detail~) => "UiResourceError::HandlerFailed(\{detail})"
    SnapshotRequired(reason~) => "UiResourceError::SnapshotRequired(\{reason})"
  }
}

///|
/// One action delivered back to the publishing extension.
#derive(Eq, Debug)
pub(all) struct UiActionInvocation {
  resource : UiResourceRef
  revision : Int32
  action : String
  request_id : String
  payload : Json?
}

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

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

///|
/// Owner-supplied action handler. Returning `Err` reports a handled failure;
/// raising is caught by the runtime and reported as `HandlerFailed`.
pub type UiActionHandler = async (UiActionInvocation) -> Result[Unit, String]

///|
/// Owner-bound capability delivered through `CompositionView::ui_resources`.
pub struct UiResources {
  priv owner_ : String
  priv publish_ : (UiResourceDraft) -> Result[
    UiResourceSnapshot,
    UiResourceError,
  ]
  priv replace_ : (UiResourceDraft, Int32) -> Result[
    UiResourceSnapshot,
    UiResourceError,
  ]
  priv remove_ : (UiResourceRef) -> Result[Int32, UiResourceError]
  priv set_action_handler_ : (UiActionHandler) -> Result[Unit, UiResourceError]
  priv host_support_ : (UiResourceRef) -> Result[
    Array[UiHostConnectionSupport],
    UiResourceError,
  ]
  priv operation_ : (() -> Result[UiResources, UiResourceError])?
}

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

///|
/// Create the resource, or fully replace it when this owner already published
/// the same key. Returns the accepted snapshot (with its new revision).
pub fn UiResources::publish(
  self : UiResources,
  draft~ : UiResourceDraft,
) -> Result[UiResourceSnapshot, UiResourceError] {
  (self.publish_)(draft)
}

///|
/// Full replacement guarded by `expected` (the revision the caller last read).
/// A missing resource is `NotFound`; a different live revision is
/// `StaleRevision` and changes nothing.
pub fn UiResources::replace(
  self : UiResources,
  draft~ : UiResourceDraft,
  expected~ : Int32,
) -> Result[UiResourceSnapshot, UiResourceError] {
  (self.replace_)(draft, expected)
}

///|
/// Withdraw this owner's resource. Returns the last live revision; repeating
/// the withdrawal is `NotFound`.
pub fn UiResources::remove(
  self : UiResources,
  resource~ : UiResourceRef,
) -> Result[Int32, UiResourceError] {
  (self.remove_)(resource)
}

///|
/// Install the owner's action handler. Registering again replaces the previous
/// handler; after `Agent::shutdown` registration is rejected with `Closed`.
pub fn UiResources::set_action_handler(
  self : UiResources,
  handler~ : UiActionHandler,
) -> Result[Unit, UiResourceError] {
  (self.set_action_handler_)(handler)
}

///|
/// Ask every connected host how it can display this resource, in attach order.
/// Each entry is per connection (`Native` / `Fallback` / `Unsupported`); an
/// empty result means no host is connected.
pub fn UiResources::host_support(
  self : UiResources,
  resource~ : UiResourceRef,
) -> Result[Array[UiHostConnectionSupport], UiResourceError] {
  (self.host_support_)(resource)
}

///|
/// Capture the currently admitted operation as a restricted handle: calls
/// through it only touch resources bound to that operation and accept only
/// `OperationBound` drafts. Every call is refused with `InvalidInput` once
/// the operation settles, and without an admitted operation the call itself
/// is refused.
pub fn UiResources::operation(
  self : UiResources,
) -> Result[UiResources, UiResourceError] {
  match self.operation_ {
    Some(acquire) => acquire()
    None => Err(Unsupported(feature="operation-scoped UI capability"))
  }
}

///|
/// Framework construction hook. Omitting `operation` or `host_support` makes
/// the corresponding calls report `Unsupported`.
pub fn UiResources::from_callbacks(
  owner~ : String,
  publish~ : (UiResourceDraft) -> Result[UiResourceSnapshot, UiResourceError],
  replace~ : (UiResourceDraft, Int32) -> Result[
    UiResourceSnapshot,
    UiResourceError,
  ],
  remove~ : (UiResourceRef) -> Result[Int32, UiResourceError],
  set_action_handler~ : (UiActionHandler) -> Result[Unit, UiResourceError],
  operation? : () -> Result[UiResources, UiResourceError],
  host_support? : (UiResourceRef) -> Result[
    Array[UiHostConnectionSupport],
    UiResourceError,
  ],
) -> UiResources {
  let support_callback = match host_support {
    Some(callback) => callback
    None => fn(_resource) { Err(Unsupported(feature="host capability query")) }
  }
  {
    owner_: owner,
    publish_: publish,
    replace_: replace,
    remove_: remove,
    set_action_handler_: set_action_handler,
    host_support_: support_callback,
    operation_: operation,
  }
}