colmugx/posoco/port does not have a README file

    ToolRetire

    type ToolRetire = async () -> Result[Unit, String]

    Optional version cleanup callback supplied by the publishing owner. Core calls it once the version is neither active nor referenced by any operation or unconfirmed execution. Return Err(detail) for a failed cleanup; core also bounds the call. Either failure keeps the version pending for a later retry, so the callback must be safe to run again.

    UiActionHandler

    type UiActionHandler = async (UiActionInvocation) -> Result[Unit, String]

    Owner-supplied action handler. Returning Err reports a handled failure; raising is caught by the runtime and reported as HandlerFailed.

    CommandPort

    pub(open) trait CommandPort {
    fn commands(Self) -> Array[CommandDef]
    async fn invoke(Self, id : String, args :
    Json
    ) -> CommandOutcome raise
    CommandError

    }

    User-initiated, enumerable, side-effecting commands. Distinct from ToolProvider (LLM-initiated, results re-enter session). Both panel TUIs and slash command lines consume this without knowing command semantics. pub(open) so any ext can declare commands.

    DecisionPort

    pub(open) trait DecisionPort {
    async fn evaluate(Self, request : DecisionRequest, context~ : DecisionCallContext) -> DecisionResult raise
    DecisionError

    }

    A low-cost semantic judgement capability. The port does not decide final business policy: consumers map the returned probabilities into their own deterministic policy and authority flow.

    Extension

    pub(open) trait Extension {
    fn extension_id(Self) -> String
    fn manifest(Self) -> ExtensionManifest
    }

    Lifecycle

    pub(open) trait Lifecycle {
    fn on_compose(Self, ctx : CompositionView) -> Unit raise
    CompositionError
    = _
    async fn on_start(Self) -> Unit = _
    async fn on_shutdown(Self) -> Unit = _
    }

    Lifecycle: the extension-facing agent lifecycle, three phases.

    • on_compose: called once, synchronously, after every composition gate has passed (catalog atomic snapshot, model cardinality, collision checks) and before the Agent is ready. This is where the composed capabilities declared in the manifest's requires are delivered via CompositionView. Sync on purpose: ModelPort::chat and UiPort::request are async, so a sync composition point cannot use what it wires — the type system enforces "wire, don't act". Raise CompositionError::ExtensionComposeFailed to fail the composition loudly; no partial Agent is produced.
    • on_start: called once per Agent lifetime, inside the first run_turn (an async context), before the first TurnStarted is projected. This is the legitimate birth point for loading persisted state or spawning background loops — construction time has no async root. Not re-fired after Suspended resumes. Like other async slots the body may raise; the Agent wraps a raised error loudly and the first turn fails before any terminal event is emitted.
    • on_shutdown: resource cleanup hook, called once on agent shutdown in reverse registration order; cleanup failure propagates (loud).

    All methods have defaults: an extension overrides only the phases it cares about, and adding a phase is non-breaking (same pattern as PipelineHook).

    LogPort

    pub(open) trait LogPort {
    async fn write(Self, record : LogRecord, durability : LogDurability) -> Unit raise
    LogError

    async fn flush(Self) -> Unit raise
    LogError

    }

    Structured logging port.

    Implementations must preserve call order for writes observed through the same LogPort instance and honour the requested durability before returning. flush commits any buffered records according to the sink's normal durable flush semantics. Implementations should validate records with LogRecord::validate before accepting them.

    MemoryPort

    pub(open) trait MemoryPort {
    async fn inbound(Self, session_id~ : String, request~ : String) -> String? raise
    MemoryError

    async fn store(Self, content~ : String, metadata~ : Map[String,
    Json
    ]) -> String raise
    MemoryError

    async fn search(Self, query~ : String, top_k? : Int) -> String? raise
    MemoryError

    async fn delete(Self, id : String) -> Unit raise
    MemoryError

    }

    MemoryPort: session memory — the port a memory system plugs into (nowledge-mem today, OpenViking and any other scheme tomorrow). Four slots: inbound for session-opening recall, store/search/delete for the durable record. Core never labels or re-renders provider output — providers own their text format (community convention e.g. devkit envelopes); core owns only timing, placement, and stability.

    ModelPort

    ModelPort: LLM calling interface. Decides HOW to compact; posoco decides WHEN. chat returns ModelCallResult with processed_messages.

    Both model-side entry points receive an InvocationScope identifying the session/run the call serves (chat additionally carries the reducer- allocated effect id). Adapters that key behaviour on session identity — continuity, telemetry, cost attribution, per-session policy — read it from scope; scope-agnostic adapters ignore it. Treat it as read-only.

    Observer

    pub(open) trait Observer {
    fn on_event(Self, scope :
    EventScope
    ?, event :
    TurnEvent
    ) -> Unit = _
    }

    Read-only committed event projection. Run-bound events carry attribution; operation-level diagnostics may have no run scope. Use PipelineHook for interception, approval or asynchronous side effects.

    PipelineHook

    pub(open) trait PipelineHook {
    fn tool_exposure(Self, definition :
    ToolDef
    ) ->
    ToolExposure
    = _
    async fn before_model(Self, messages : Array[
    Message
    ]) -> Array[
    Message
    ] raise HookAbort = _
    async fn before_tool(Self, call :
    ToolCall
    ) -> ToolDecision = _
    async fn on_post_event(Self, scope :
    EventScope
    ?, stage : HookStage) -> Unit noraise = _
    async fn on_turn_begin(Self) -> Unit = _
    async fn on_turn_end(Self) -> Unit = _
    }

    Pipeline interception points covering nearly the whole agent lifecycle: turn begin/end, before/after the model, before/after tools. Registration is unified: an extension puts self (or any implementor) into the manifest's single hooks array and overrides the methods for the points it cares about.

    • on_turn_begin: async turn-start slot. Dispatched once per run_single_turn, after the TurnStarted observer projection and before the pump's first before_model. Symmetric with on_turn_end: pre-turn failures (agent-shutdown guard, lifecycle on_start raises) dispatch nothing — the turn never began. A raise is a secondary failure — reported to observers, never failing the turn — and later hooks still run; cancellation is not a defect.
    • before_model: invoked at turn entry and before requests carrying new wakeup input. It can rewrite the candidate messages or raise HookAbort. Each hook sees the previous hook's output. Reading a new wakeup at the first model boundary may run the chain again after turn entry.
    • before_tool: invoked before every tool execution. Every hook is evaluated; merge precedence on ToolDecision (consent beats Reject; Defer still aborts the run).
    • on_post_event: read-only, non-raising notification with the committing run's EventScope. Hooks run in registration order; interception belongs in before_model or before_tool.
    • on_turn_end: async turn-end slot, no payload. The terminal outcome already lives on the Observer channel — TurnCompleted / TurnFailed(String) / TurnCancelled — and an extension typically implements Observer and PipelineHook as two views over one shared struct, so a hook that needs the outcome reads its own observer-side state instead of a second payload type. Dispatched once per turn that reaches a typed terminal, after the terminal observer projection and before that turn returns — on the completed, failed and cancelled paths alike. One run_turn may drain several follow-up turns inside one operation; each turn dispatches its own pair. This is the slot for side effects that must finish by turn end, such as committing buffered writes to an external system. Implementations must carry their own timeout budget and may not block the turn's return indefinitely. Division of labor with Observer::on_event(TurnCompleted): the observer slot is sync, read-only and fires first; on_turn_end may await. A raise from on_turn_end is a secondary failure — reported to observers, never replacing the turn's primary outcome — and cancellation is not a defect.

      A hard cancellation that unwinds the turn outside every catch does not dispatch this hook; the Observer still receives TurnCancelled.

    Async spread: the slots are async, so IO in an implementation body propagates through async. The pipeline dispatches hooks sequentially — each hook is awaited before the next runs — and never opens a thread or worker, so registration order is preserved at every point.

    SessionPort

    pub(open) trait SessionPort {
    async fn load(Self, id : String) ->
    Session
    raise
    SessionError

    async fn save(Self, id : String, session :
    Session
    ) -> Unit raise
    SessionError

    async fn append_messages(Self, id : String, from_index : Int, messages : ArrayView[
    Message
    ]) -> Unit raise
    SessionError
    = _
    async fn checkpoint(Self, id : String, checkpoint : SessionCheckpoint) -> Unit raise
    SessionError
    = _
    async fn truncate(Self, id : String, from_index : Int) -> Unit raise
    SessionError
    = _
    }

    SystemPromptContributor

    pub(open) trait SystemPromptContributor {
    fn system_prompt(Self) -> String
    }

    Returns a section of the system prompt. Blank returns (whitespace only) are skipped; a non-blank return is included verbatim.

    Stability contract: the returned text MUST be byte-for-byte identical for the entire lifetime of one Agent. Posoco reads each contributor exactly once — during the first turn's first before_model call — and caches the assembled result. Dynamic signals (e.g. plan-mode toggles) MUST NOT be implemented as contributors; inject them through PipelineHook::before_model instead. A message injected there is persisted with the session, so keep such notifications idempotent.

    ToolCancellable

    Cancellation facet a ToolProvider may also implement for effects it owns. Register via ToolCallContext.register_cancel inside execute; the runtime routes a later cancel back through the same effect_id.

    Idempotent per execution. Propagated means only that a signal was sent; Stopped requires confirmation that owned work has stopped (not rollback). Return AlreadySettled for previously completed work. Core bounds cleanup attempts and retains unresolved registrations on failure or timeout so shutdown can retry; never disguise an error as confirmed termination.

    ToolProvider

    pub(open) trait ToolProvider {
    fn list_tools(Self) -> Array[
    ToolDef
    ]
    async fn execute(Self, ctx : ToolCallContext) ->
    ToolOutcome
    raise
    RuntimeError

    }

    ToolProvider: declare tools via list_tools(), execute via execute().

    Agent binds each definition's owner to the declaring manifest. Providers declare their own execution policy and exposure; these are not inferred from names or provenance. execute returns the canonical ToolOutcome.

    A composing tool must reserve a policy strong enough for its children: Parallel cannot invoke Sequential/Exclusive; Sequential cannot invoke Exclusive. Such requests are rejected before starting, not upgraded at runtime. The parent's scheduling slot covers the whole joined subtree.

    UiPort

    pub(open) trait UiPort {
    fn ui_descriptor(Self) -> UiDescriptor
    fn render(Self, intent : UiRender) -> Unit
    async fn request(Self, req : UiRequest) -> UiResponse raise
    UiError

    }

    The UI extension contract. Implemented by host packages (cetas-js, cetas-native) or testkit.

    HookAbort

    pub(all) suberror HookAbort {
    Aborted(reason~ : String)
    }

    Raised by PipelineHook::before_model to stop the run before the model is called.
    impl Show for HookAbort

    HookAbort::output

    fn HookAbort::output(self : HookAbort, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    HookAbort::to_string

    fn HookAbort::to_string(self : HookAbort) -> String

    AutocompleteItem

    pub(all) struct AutocompleteItem {
    label : String
    insert_text : String
    detail : String?
    kind : String
    } derive(
    Debug
    )

    AutocompleteItem::to_repr

    automatically derived

    AutocompleteSource

    pub(all) struct AutocompleteSource {
    trigger : String
    kind : String
    fetch : (String) -> Array[AutocompleteItem]
    } derive(
    Debug
    )

    A source of autocomplete suggestions tied to a trigger character.

    AutocompleteSource::to_repr

    automatically derived

    Capability

    pub(all) enum Capability {
    Model
    Decision
    Log
    Ui
    Tasks
    Wakeup
    ToolContribution
    Events
    } derive(Eq,
    Debug
    )

    A composed capability an extension declares it consumes. Declaring is what populates the CompositionView delivered at Lifecycle::on_compose — the view gates on this declaration, so an undeclared capability reads as None. Extensible by adding variants; existing manifests are unaffected.

    Capability::equal

    fn Capability::equal(Capability, Capability) -> Bool
    automatically derived

    Capability::not_equal

    fn Capability::not_equal(x : Capability, y : Capability) -> Bool
    automatically derived

    Capability::to_repr

    automatically derived

    CommandDef

    pub(all) struct CommandDef {
    id : String
    label : String
    description : String
    category : String
    ctype : CommandType
    params : Array[CommandParam]
    aliases : Array[String]
    shortcut : String?
    icon : String?
    visible : Bool
    metadata :
    Json
    ?
    } derive(Eq,
    Debug
    )

    Command declaration. params is the source of truth for argument rendering (panel form) and parsing (slash). Redundant fields (aliases/shortcut/icon/ visible/metadata) are deliberate "escape hatches" for ext authors to use without changing the trait — meta does not define their semantics.

    CommandDef::equal

    fn CommandDef::equal(CommandDef, CommandDef) -> Bool
    automatically derived

    CommandDef::not_equal

    fn CommandDef::not_equal(x : CommandDef, y : CommandDef) -> Bool
    automatically derived

    CommandDef::to_repr

    automatically derived

    CommandOutcome

    pub(all) enum CommandOutcome {
    Success(feedback~ : String, structured~ :
    Json
    ?, ui_hint~ : UiHint?)
    Failure(reason~ : String)
    NeedsInput(prompt~ : String)
    } derive(Eq,
    Debug
    )

    Outcome of invoking a command. feedback is for slash (print directly); structured + ui_hint are for panel (deep render + UI action). NeedsInput supports multi-step commands.

    CommandOutcome::equal

    automatically derived

    CommandOutcome::not_equal

    fn CommandOutcome::not_equal(x : CommandOutcome, y : CommandOutcome) -> Bool
    automatically derived

    CommandOutcome::to_repr

    automatically derived

    CommandParam

    pub(all) struct CommandParam {
    name : String
    label : String
    description : String
    ptype : ParamType
    required : Bool
    default :
    Json
    ?
    choices : Array[String]?
    positional : Bool
    } derive(Eq,
    Debug
    )

    A single command parameter. Explicit and human-facing, in contrast to ToolDef.input_schema (which is JSON Schema for LLM consumption).

    CommandParam::equal

    automatically derived

    CommandParam::not_equal

    fn CommandParam::not_equal(x : CommandParam, y : CommandParam) -> Bool
    automatically derived

    CommandParam::to_repr

    automatically derived

    CommandType

    pub(all) enum CommandType {
    Action
    Toggle
    Select
    Input
    MultiStep
    } derive(Eq,
    Debug
    )

    Semantic command type. Determines how a panel renders the control (button / toggle / dropdown / input / multi-step form) and how a slash parser expects arguments.

    CommandType::equal

    fn CommandType::equal(CommandType, CommandType) -> Bool
    automatically derived

    CommandType::not_equal

    fn CommandType::not_equal(x : CommandType, y : CommandType) -> Bool
    automatically derived

    CommandType::to_repr

    automatically derived

    CompositionView

    pub struct CompositionView {
    // private fields
    }

    CompositionView: the curated read-only view of composed capabilities delivered to Lifecycle::on_compose after every composition gate has passed. This is the consumption direction of the manifest contract — an extension declares requires and the corresponding getter reads Some; undeclared capabilities read None.

    Curation discipline: the view only ever carries capabilities whose use cannot bypass governance. model calls still carry InvocationScope attribution; ui has no governance surface. The view NEVER exposes tool invocation (would bypass PipelineHook::before_tool), session stores (state ownership), or core-namespace event emission. Events only permits publication in the declaring extension's namespace. Fields are private with getters so new capabilities can be added without breaking extensions that destructure or construct views in tests.

    CompositionView::decision

    fn CompositionView::decision(self : CompositionView) -> &DecisionPort?

    Visible only when the extension declared Capability::Decision. Absence is legal: consumers that treat decision support as an enhancement keep their deterministic fallback, and consumers that require it may fail in on_compose.

    CompositionView::events

    Present only when the extension declares Capability::Events. Publication is bound to its manifest id; listening may include any namespace.

    CompositionView::log

    Visible only when the extension declared Capability::Log. Absence is legal: consumers decide whether a missing sink is acceptable.

    CompositionView::model

    Present only when the extension declared Capability::Model. The value is source-agnostic: an extension cannot tell a plain provider from a routing meta-extension, and must not.

    CompositionView::resolve

    fn CompositionView::resolve(requires~ : Array[Capability], model~ : &ModelPort, decision? : &DecisionPort?, log? : &LogPort?, ui~ : &UiPort, ui_resources? : UiResources?, ui_interactions? : UiInteractions?, tasks? : Tasks?, wakeup? : WakeupPort?, tool_contributions? : ToolContributions?, events? :
    Events
    ?) -> CompositionView

    Gate a view on a manifest's declared requires: a declared capability is populated from the composed ports, an undeclared one reads None. Called by the composition after every gate has passed, so model and ui are guaranteed to be the final composed values.

    CompositionView::tasks

    fn CompositionView::tasks(self : CompositionView) -> Tasks?

    Present only when the extension declares Capability::Tasks.

    CompositionView::tool_contributions

    fn CompositionView::tool_contributions(self : CompositionView) -> ToolContributions?

    Present only when the extension declares Capability::ToolContribution. The value is bound to this extension's manifest id, so it can only publish its own group.

    CompositionView::ui

    Present only when the extension declared Capability::Ui. Declaring ui only to consume the composed UI is not allowed.

    CompositionView::ui_interactions

    fn CompositionView::ui_interactions(self : CompositionView) -> UiInteractions?

    Present only when the extension declares Capability::Ui; bound to this extension's manifest id.

    CompositionView::ui_resources

    fn CompositionView::ui_resources(self : CompositionView) -> UiResources?

    Present only when the extension declared Capability::Ui; bound to this extension's manifest id.

    CompositionView::wakeup

    Present only when the extension declares Capability::Wakeup. request queues one ordinary turn for a session; execution stays inside the Agent's single-operation lifecycle.

    DecisionAnswer

    pub(all) enum DecisionAnswer {
    BooleanAnswer(id~ : String, probability_true~ : Double)
    ChoiceAnswer(id~ : String, selected~ : String, probabilities~ : Array[DecisionNamedProbability], confidence~ : Double?)
    ScoreAnswer(id~ : String, score~ : Double, probabilities~ : Array[Double], confidence~ : Double?)
    } derive(Eq,
    Debug
    )

    Provider-neutral typed answer. The question id is repeated so adapters can be validated without relying on response ordering.

    DecisionAnswer::equal

    automatically derived

    DecisionAnswer::not_equal

    fn DecisionAnswer::not_equal(x : DecisionAnswer, y : DecisionAnswer) -> Bool
    automatically derived

    DecisionAnswer::to_repr

    automatically derived

    DecisionCallContext

    pub(all) struct DecisionCallContext {
    purpose : String
    scope : DecisionScope?
    timeout_ms : Int?
    failure_mode : DecisionFailureMode
    } derive(Eq,
    Debug
    )

    Per-call context for DecisionPort::evaluate. Build with DecisionCallContext::make; every field except purpose is optional.

    DecisionCallContext::equal

    automatically derived

    DecisionCallContext::make

    fn DecisionCallContext::make(purpose~ : String, scope? : DecisionScope, timeout_ms? : Int, failure_mode? : DecisionFailureMode) -> DecisionCallContext

    Construct a DecisionCallContext. scope and timeout_ms default to None ("no explicit fact"); failure_mode defaults to Propagate.

    DecisionCallContext::not_equal

    automatically derived

    DecisionCallContext::to_repr

    automatically derived

    DecisionFailureMode

    pub(all) enum DecisionFailureMode {
    Fallback
    FailClosed
    Propagate
    } derive(Eq,
    Debug
    )

    Consumer-declared failure handling for a contextual call. Diagnostics and attribution only: the actual policy (which fallback, whether to close) is executed by the consuming extension, never by this port.

    DecisionFailureMode::equal

    automatically derived

    DecisionFailureMode::not_equal

    automatically derived

    DecisionFailureMode::to_repr

    automatically derived

    DecisionNamedProbability

    pub(all) struct DecisionNamedProbability {
    id : String
    probability : Double
    } derive(Eq,
    Debug
    )

    One named probability in a choice distribution.

    DecisionNamedProbability::equal

    automatically derived

    DecisionNamedProbability::not_equal

    automatically derived

    DecisionNamedProbability::to_repr

    automatically derived

    DecisionOption

    pub(all) struct DecisionOption {
    id : String
    description :
    Json
    ?
    } derive(Eq,
    Debug
    )

    One named alternative for a Choice question.

    DecisionOption::equal

    automatically derived

    DecisionOption::not_equal

    fn DecisionOption::not_equal(x : DecisionOption, y : DecisionOption) -> Bool
    automatically derived

    DecisionOption::to_repr

    automatically derived

    DecisionQuestion

    pub(all) enum DecisionQuestion {
    Boolean(id~ : String, instructions~ :
    Json
    , true_criteria~ :
    Json
    ?, false_criteria~ :
    Json
    ?)
    Choice(id~ : String, instructions~ :
    Json
    , options~ : Array[DecisionOption])
    Score(id~ : String, instructions~ :
    Json
    , levels~ : Array[
    Json
    ])
    } derive(Eq,
    Debug
    )

    Typed question understood by a DecisionPort.

    DecisionQuestion::equal

    automatically derived

    DecisionQuestion::not_equal

    fn DecisionQuestion::not_equal(x : DecisionQuestion, y : DecisionQuestion) -> Bool
    automatically derived

    DecisionQuestion::to_repr

    automatically derived

    DecisionRequest

    pub(all) struct DecisionRequest {
    state :
    Json

    questions : Array[DecisionQuestion]
    } derive(Eq,
    Debug
    )

    Structured state plus a non-empty set of independent semantic questions.

    DecisionRequest::equal

    automatically derived

    DecisionRequest::not_equal

    fn DecisionRequest::not_equal(x : DecisionRequest, y : DecisionRequest) -> Bool
    automatically derived

    DecisionRequest::to_repr

    automatically derived

    DecisionRequest::validate

    Validate provider-neutral request invariants before an adapter builds its wire request. Providers may impose additional limits, but must not accept requests that violate these base invariants.

    DecisionResult

    pub(all) struct DecisionResult {
    answers : Array[DecisionAnswer]
    model : String?
    usage : DecisionUsage?
    } derive(Eq,
    Debug
    )

    Typed answers plus provider-reported model/usage metadata. model is descriptive observability only; consumers must not branch policy on a provider identity hidden behind this port.

    DecisionResult::equal

    automatically derived

    DecisionResult::not_equal

    fn DecisionResult::not_equal(x : DecisionResult, y : DecisionResult) -> Bool
    automatically derived

    DecisionResult::to_repr

    automatically derived

    DecisionResult::validate_for

    Validate a provider result against the request that produced it. Adapters should call this before returning so malformed or semantically mismatched provider payloads fail loudly as DecisionError::ResponseParse.

    DecisionScope

    pub(all) struct DecisionScope {
    session : String
    } derive(Eq,
    Debug
    )

    Explicit scope fact known at the call site (e.g. the session a background task belongs to when the caller actually knows it). Unknown scope is expressed as None by the caller; this port never infers scope from the active run or background-task ownership.

    DecisionScope::equal

    automatically derived

    DecisionScope::not_equal

    fn DecisionScope::not_equal(x : DecisionScope, y : DecisionScope) -> Bool
    automatically derived

    DecisionScope::to_repr

    automatically derived

    DecisionUsage

    pub(all) struct DecisionUsage {
    input_tokens : Int?
    output_tokens : Int?
    } derive(Eq,
    Debug
    )

    Optional token accounting supplied by decision providers.

    DecisionUsage::equal

    automatically derived

    DecisionUsage::not_equal

    fn DecisionUsage::not_equal(x : DecisionUsage, y : DecisionUsage) -> Bool
    automatically derived

    DecisionUsage::to_repr

    automatically derived

    ExtensionManifest

    pub(all) struct ExtensionManifest {
    id : String
    models : Array[&ModelPort]
    decisions : Array[&DecisionPort]
    logs : Array[&LogPort]
    tools : Array[&ToolProvider]
    sessions : Array[&SessionPort]
    observers : Array[&Observer]
    hooks : Array[&PipelineHook]
    memory : Array[&MemoryPort]
    lifecycle : Array[&Lifecycle]
    commands : Array[&CommandPort]
    ui : Array[&UiPort]
    prompt_contributors : Array[&SystemPromptContributor]
    requires : Array[Capability]
    tool_call_owners : Array[String]
    }

    Self-reported port contributions. Build one with ExtensionManifest::make, which defaults every omitted field to an empty array; multi-trait extensions put self under each applicable field.

    requires is the consumption direction: the extension declares which composed capabilities it wants delivered at Lifecycle::on_compose. The declaration is load-bearing (the view gates on it) and auditable (composition can answer "which extensions declared model access").

    ExtensionManifest::ExtensionManifest

    fn ExtensionManifest::ExtensionManifest(id~ : String, models? : Array[&ModelPort], decisions? : Array[&DecisionPort], logs? : Array[&LogPort], tools? : Array[&ToolProvider], sessions? : Array[&SessionPort], observers? : Array[&Observer], hooks? : Array[&PipelineHook], memory? : Array[&MemoryPort], lifecycle? : Array[&Lifecycle], commands? : Array[&CommandPort], ui? : Array[&UiPort], prompt_contributors? : Array[&SystemPromptContributor], requires? : Array[Capability], tool_call_owners? : Array[String]) -> ExtensionManifest

    ExtensionManifest::default

    fn ExtensionManifest::default(id~ : String) -> ExtensionManifest

    Construct an empty manifest with only the id set. Fields can then be assigned individually.

    HookStage

    pub(all) enum HookStage {
    ModelCompleted(completion~ :
    Completion
    )
    ToolCompleted(call~ :
    ToolCall
    , outcome~ :
    ToolOutcome
    )
    ToolFailed(call~ :
    ToolCall
    , reason~ : String)
    ModelFailed(failure~ :
    ModelFailure
    )
    } derive(
    Debug
    )

    Describes what just completed, delivered after the effect is committed.
    impl Show for HookStage

    HookStage::output

    fn HookStage::output(self : HookStage, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    HookStage::to_repr

    automatically derived

    HookStage::to_string

    fn HookStage::to_string(self : HookStage) -> String

    LogDurability

    pub(all) enum LogDurability {
    Buffered
    Written
    Durable
    } derive(Eq,
    Debug
    )

    Persistence acknowledgement requested by a log producer.

    • Buffered: the sink accepted the record; it may still live only in memory.
    • Written: the sink completed its normal write path.
    • Durable: the sink crossed its durability barrier before returning.

    LogDurability::equal

    automatically derived

    LogDurability::not_equal

    fn LogDurability::not_equal(x : LogDurability, y : LogDurability) -> Bool
    automatically derived

    LogDurability::to_repr

    automatically derived

    LogLevel

    pub(all) enum LogLevel {
    Trace
    Debug
    Info
    Warn
    Error
    } derive(Eq,
    Debug
    )

    LogLevel::equal

    fn LogLevel::equal(LogLevel, LogLevel) -> Bool
    automatically derived

    LogLevel::not_equal

    fn LogLevel::not_equal(x : LogLevel, y : LogLevel) -> Bool
    automatically derived

    LogLevel::to_repr

    automatically derived

    LogRecord

    pub(all) struct LogRecord {
    level : LogLevel
    source : String
    channel : String
    event : String
    message : String?
    scope :
    EventScope
    ?
    data :
    Json

    } derive(Eq,
    Debug
    )

    Provider-neutral structured log record.

    source, channel, and event are stable machine-readable identifiers. message is optional human-readable context. scope attributes records to a Posoco session/run/turn when one exists. data is producer-owned JSON; sinks must not inspect it to infer secrets or policy.

    LogRecord::equal

    fn LogRecord::equal(LogRecord, LogRecord) -> Bool
    automatically derived

    LogRecord::not_equal

    fn LogRecord::not_equal(x : LogRecord, y : LogRecord) -> Bool
    automatically derived

    LogRecord::to_repr

    automatically derived

    LogRecord::validate

    Validate the protocol-level fields that every sink may rely on.

    ParamType

    pub(all) enum ParamType {
    Str
    Int
    Bool
    Strs
    } derive(Eq,
    Debug
    )

    Value type of a command parameter. Human-friendly (unlike JSON Schema which targets LLMs). Panel/slash consumers render and parse directly from this.

    ParamType::equal

    fn ParamType::equal(ParamType, ParamType) -> Bool
    automatically derived

    ParamType::not_equal

    fn ParamType::not_equal(x : ParamType, y : ParamType) -> Bool
    automatically derived

    ParamType::to_repr

    automatically derived

    ProviderConfig

    pub(all) struct ProviderConfig {
    reasoning_effort_values : Array[String]
    context_window : Int?
    compact_threshold : Double?
    } derive(Eq,
    Debug
    )

    ProviderConfig: modelport's self-description of accepted config values. A String array (not typed enum) because each provider has its own vocabulary for e.g. reasoning_effort values.

    ProviderConfig::ProviderConfig

    fn ProviderConfig::ProviderConfig(reasoning_effort_values~ : Array[String], context_window? : Int?, compact_threshold? : Double?) -> ProviderConfig

    ProviderConfig::accepts_reasoning_effort

    fn ProviderConfig::accepts_reasoning_effort(self : ProviderConfig, value : String) -> Bool

    Check if the given reasoning_effort value is accepted.

    ProviderConfig::empty

    Empty config: no reasoning_effort values accepted, no window reported.

    ProviderConfig::equal

    automatically derived

    ProviderConfig::not_equal

    fn ProviderConfig::not_equal(x : ProviderConfig, y : ProviderConfig) -> Bool
    automatically derived

    ProviderConfig::output

    fn ProviderConfig::output(self : ProviderConfig, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    ProviderConfig::to_repr

    automatically derived

    ProviderConfig::to_string

    fn ProviderConfig::to_string(self : ProviderConfig) -> String

    SessionCheckpoint

    pub(all) struct SessionCheckpoint {
    from_index : Int
    messages : Array[
    Message
    ]
    metadata : Map[String,
    Json
    ]?
    } derive(Eq,
    Debug
    )

    One append-safe session durability boundary. from_index is the number of messages the caller believes are already persisted. messages is the canonical tail to append. metadata=None means metadata is unchanged; Some(metadata) replaces the session metadata at the same checkpoint.

    Keeping message and metadata deltas in one operation prevents callers from committing transcript progress while silently dropping session state such as an automatic title, context state, or task bookkeeping.

    SessionCheckpoint::equal

    automatically derived

    SessionCheckpoint::not_equal

    fn SessionCheckpoint::not_equal(x : SessionCheckpoint, y : SessionCheckpoint) -> Bool
    automatically derived

    SessionCheckpoint::to_repr

    automatically derived

    TaskHandle

    pub struct TaskHandle {
    // private fields
    }

    Opaque handle for one admitted task. The callbacks are installed by core composition; extensions only receive wait/cancel operations.

    TaskHandle::cancel

    fn TaskHandle::cancel(self : TaskHandle) -> Unit

    TaskHandle::from_callbacks

    fn TaskHandle::from_callbacks(receipt~ : TaskReceipt, wait~ : async (TaskReceipt) -> TaskOutcome, cancel~ : (TaskReceipt) -> Unit) -> TaskHandle

    Framework construction hook for the opaque handle.

    TaskHandle::receipt

    fn TaskHandle::receipt(self : TaskHandle) -> TaskReceipt

    TaskHandle::wait

    async fn TaskHandle::wait(self : TaskHandle) -> TaskOutcome

    TaskMode

    pub(all) enum TaskMode {
    Foreground
    Background
    } derive(Eq,
    Debug
    )

    Execution lifetime for work submitted through the composed task capability.

    TaskMode::equal

    fn TaskMode::equal(TaskMode, TaskMode) -> Bool
    automatically derived

    TaskMode::not_equal

    fn TaskMode::not_equal(x : TaskMode, y : TaskMode) -> Bool
    automatically derived

    TaskMode::to_repr

    automatically derived

    TaskOutcome

    pub(all) struct TaskOutcome {
    receipt : TaskReceipt
    status : TaskStatus
    } derive(Eq,
    Debug
    )

    A task's terminal result. Background outcomes are retained by session until the owning Agent successfully commits them.

    TaskOutcome::equal

    fn TaskOutcome::equal(TaskOutcome, TaskOutcome) -> Bool
    automatically derived

    TaskOutcome::not_equal

    fn TaskOutcome::not_equal(x : TaskOutcome, y : TaskOutcome) -> Bool
    automatically derived

    TaskOutcome::to_repr

    automatically derived

    TaskReceipt

    pub(all) struct TaskReceipt {
    id : String
    session_id : String
    mode : TaskMode
    label : String
    extension_id : String
    } derive(Eq,
    Debug
    )

    Stable identity returned at admission. The id is opaque to the caller.

    TaskReceipt::equal

    fn TaskReceipt::equal(TaskReceipt, TaskReceipt) -> Bool
    automatically derived

    TaskReceipt::not_equal

    fn TaskReceipt::not_equal(x : TaskReceipt, y : TaskReceipt) -> Bool
    automatically derived

    TaskReceipt::to_repr

    automatically derived

    TaskSpec

    pub(all) struct TaskSpec {
    session_id : String
    mode : TaskMode
    label : String
    timeout_ms : Int?
    run : async () ->
    Message

    }

    A unit of Agent-owned work. The Agent supplies the structured scope and records the terminal outcome; callers never supply a TaskGroup.

    TaskStatus

    pub(all) enum TaskStatus {
    Completed(message~ :
    Message
    )
    Failed(reason~ : String)
    TimedOut
    Cancelled(reason~ : String)
    } derive(Eq,
    Debug
    )

    The single terminal state shared by foreground waits and background inbox delivery.

    TaskStatus::equal

    fn TaskStatus::equal(TaskStatus, TaskStatus) -> Bool
    automatically derived

    TaskStatus::not_equal

    fn TaskStatus::not_equal(x : TaskStatus, y : TaskStatus) -> Bool
    automatically derived

    TaskStatus::to_repr

    automatically derived

    TaskSubmitError

    pub(all) enum TaskSubmitError {
    Unavailable
    Closed
    QueueFull
    InvalidSession(reason~ : String)
    } derive(Eq,
    Debug
    )

    Admission failures are explicit so an extension cannot mistake an inactive scope or a closed Agent for accepted work.

    TaskSubmitError::equal

    automatically derived

    TaskSubmitError::not_equal

    fn TaskSubmitError::not_equal(x : TaskSubmitError, y : TaskSubmitError) -> Bool
    automatically derived

    TaskSubmitError::to_repr

    automatically derived

    Tasks

    pub struct Tasks {
    // private fields
    }

    Concrete composed capability. It is deliberately a value rather than a public trait: task admission is Agent-owned and has no replacement port.

    Tasks::from_submit

    fn Tasks::from_submit(submit~ : (TaskSpec) -> Result[TaskHandle, TaskSubmitError]) -> Tasks

    Framework construction hook. Product extensions obtain the value through CompositionView and do not need this constructor.

    Tasks::submit

    fn Tasks::submit(self : Tasks, spec : TaskSpec) -> Result[TaskHandle, TaskSubmitError]

    ToolCallContext

    Effect-scoped execution context handed to ToolProvider::execute. effect_id is the reducer-assigned identity of this ExecuteTool effect — the exact id a later cancellation carries, so a provider owning interruptible work keys its in-flight state by it.

    ToolCallContext::ToolCallContext

    Framework construction seam. An ordinary manually constructed context has no invocation authority. Supplied callbacks are local to this effect scope.

    ToolContributionCommit

    pub(all) struct ToolContributionCommit {
    owner : String
    revision : Int
    state : ToolContributionState
    } derive(Eq,
    Debug
    )

    Acknowledgement of one accepted contribution commit. revision is core-owned and monotonic per owner; it is distinct from the catalog version an operation captures at admission. state is the owner slot's state after the commit.

    ToolContributionCommit::equal

    automatically derived

    ToolContributionCommit::not_equal

    automatically derived

    ToolContributionCommit::to_repr

    automatically derived

    ToolContributionError

    pub(all) enum ToolContributionError {
    Closed
    NotContributed
    Rejected(reason~ : String)
    CleanupPending(revision~ : Int, state~ : ToolContributionState, detail~ : String)
    } derive(Eq,
    Debug
    )

    ToolContributionError::equal

    automatically derived

    ToolContributionError::not_equal

    automatically derived

    ToolContributionError::output

    fn ToolContributionError::output(self : ToolContributionError, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    ToolContributionError::to_repr

    automatically derived

    ToolContributionError::to_string

    fn ToolContributionError::to_string(self : ToolContributionError) -> String

    ToolContributionState

    pub(all) enum ToolContributionState {
    Active
    Withdrawn
    Closed
    } derive(Eq,
    Debug
    )

    Directory state of one owner slot, as reported by an ACK or a query.

    ToolContributionState::equal

    automatically derived

    ToolContributionState::not_equal

    automatically derived

    ToolContributionState::output

    fn ToolContributionState::output(self : ToolContributionState, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    ToolContributionState::to_repr

    automatically derived

    ToolContributionState::to_string

    fn ToolContributionState::to_string(self : ToolContributionState) -> String

    ToolContributions

    pub struct ToolContributions {
    // private fields
    }

    ToolContributions::from_callbacks

    fn ToolContributions::from_callbacks(owner~ : String, replace~ : async (&ToolProvider, async () -> Result[Unit, String]?) -> Result[ToolContributionCommit, ToolContributionError] noraise, withdraw~ : async (ToolWithdrawMode) -> Result[ToolContributionCommit, ToolContributionError] noraise, revision~ : () -> Int?, state~ : () -> ToolContributionState) -> ToolContributions

    Framework construction hook. Product extensions obtain the value through CompositionView and do not need this constructor.

    ToolContributions::owner

    fn ToolContributions::owner(self : ToolContributions) -> String

    The manifest id this capability is bound to.

    ToolContributions::replace

    async fn ToolContributions::replace(self : ToolContributions, provider~ : &ToolProvider, retire? : async () -> Result[Unit, String]) -> Result[ToolContributionCommit, ToolContributionError] noraise

    Atomically replace this owner's contributed group. retire becomes the cleanup callback for the newly published version's own resources.

    ToolContributions::revision

    fn ToolContributions::revision(self : ToolContributions) -> Int?

    The accepted revision this owner currently contributes, or None when nothing is contributed (never published or withdrawn).

    ToolContributions::state

    The owner slot's current state: Active, Withdrawn or Closed.

    ToolContributions::withdraw

    Withdraw this owner's contributed group. The transition increments revision; repeating the same withdrawal mode returns the current revision unchanged. A hard withdrawal after a soft one is a new revocation fact and therefore advances the revision. The tombstone retains the sequence so a later replace continues it.

    ToolDecision

    pub(all) enum ToolDecision {
    Approve(call~ :
    ToolCall
    )
    ApproveAfterConsent(call~ :
    ToolCall
    , consent_scope~ : String)
    Defer(reason~ : String)
    Reject(reason~ : String)
    } derive(
    Debug
    )

    The hook's decision for a pending tool call.

    Chain semantics: every registered hook is evaluated (no short-circuit). Precedence: a raise aborts the run; Defer terminal-rejects; ApproveAfterConsent beats Reject; Reject skips the call and feeds the joined reasons back to the model as a NotExecuted(RejectedByHook) tool result; otherwise the call executes with the chained rewrite. The complete chain is finalized before catalog validation and scheduling, so the final call determines its schema, owner, and execution policy. Consent binds to the exact call_id, name, and arguments returned by that consent decision; a later mutation cannot reuse it, and call_id is never rewriteable.

    ToolDecision::output

    fn ToolDecision::output(self : ToolDecision, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    ToolDecision::to_repr

    automatically derived

    ToolDecision::to_string

    fn ToolDecision::to_string(self : ToolDecision) -> String

    ToolWithdrawMode

    pub(all) enum ToolWithdrawMode {
    Soft
    Hard
    } derive(Eq,
    Debug
    )

    What a withdraw request means for still-live versions of the owner.

    ToolWithdrawMode::equal

    automatically derived

    ToolWithdrawMode::not_equal

    fn ToolWithdrawMode::not_equal(x : ToolWithdrawMode, y : ToolWithdrawMode) -> Bool
    automatically derived

    ToolWithdrawMode::output

    fn ToolWithdrawMode::output(self : ToolWithdrawMode, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    ToolWithdrawMode::to_repr

    automatically derived

    ToolWithdrawMode::to_string

    fn ToolWithdrawMode::to_string(self : ToolWithdrawMode) -> String

    UiActionInvocation

    pub(all) struct UiActionInvocation {
    resource : UiResourceRef
    revision : Int
    action : String
    request_id : String
    payload :
    Json
    ?
    } derive(Eq,
    Debug
    )

    One action delivered back to the publishing extension.

    UiActionInvocation::equal

    automatically derived

    UiActionInvocation::not_equal

    automatically derived

    UiActionInvocation::to_repr

    automatically derived

    UiActionPayloadKind

    pub(all) enum UiActionPayloadKind {
    NoPayload
    JsonPayload
    } derive(Eq,
    Debug
    )

    Payload shape an action accepts.

    UiActionPayloadKind::equal

    automatically derived

    UiActionPayloadKind::not_equal

    automatically derived

    UiActionPayloadKind::to_repr

    automatically derived

    UiActionRequest

    pub(all) struct UiActionRequest {
    resource : UiResourceRef
    action : String
    expected_revision : Int
    request_id : String
    payload :
    Json
    ?
    } derive(Eq,
    Debug
    )

    Host intent to run one declared action of one resource.

    UiActionRequest::equal

    automatically derived

    UiActionRequest::not_equal

    fn UiActionRequest::not_equal(x : UiActionRequest, y : UiActionRequest) -> Bool
    automatically derived

    UiActionRequest::to_repr

    automatically derived

    UiActionResult

    pub(all) struct UiActionResult {
    request_id : String
    resource : UiResourceRef
    action : String
    revision : Int
    replayed : Bool
    } derive(Eq,
    Debug
    )

    Receipt of one accepted action.

    UiActionResult::equal

    automatically derived

    UiActionResult::not_equal

    fn UiActionResult::not_equal(x : UiActionResult, y : UiActionResult) -> Bool
    automatically derived

    UiActionResult::to_repr

    automatically derived

    UiActionSpec

    pub(all) struct UiActionSpec {
    id : String
    label : String
    payload : UiActionPayloadKind
    } derive(Eq,
    Debug
    )

    One user-invokable action the resource declares.

    UiActionSpec::equal

    automatically derived

    UiActionSpec::not_equal

    fn UiActionSpec::not_equal(x : UiActionSpec, y : UiActionSpec) -> Bool
    automatically derived

    UiActionSpec::to_repr

    automatically derived

    UiBaseline

    pub(all) struct UiBaseline {
    cursor : UiCursor
    interaction_cursor : UiCursor
    resources : Array[UiResourceSnapshot]
    pending_interactions : Array[UiInteractionSnapshot]
    } derive(Eq,
    Debug
    )

    One consistent read of the UI protocol: every live resource, every pending interaction, and the cursors the host continues from.

    UiBaseline::equal

    fn UiBaseline::equal(UiBaseline, UiBaseline) -> Bool
    automatically derived

    UiBaseline::not_equal

    fn UiBaseline::not_equal(x : UiBaseline, y : UiBaseline) -> Bool
    automatically derived

    UiBaseline::to_repr

    automatically derived

    UiBody

    pub(all) enum UiBody {
    Text(String)
    Lines(Array[String])
    KeyValue(Array[(String, String)])
    Entries(Array[UiEntry])
    Progress(Double)
    Markdown(String)
    } derive(
    Debug
    )

    Structured payload a render intent carries. Host decides layout and color.
    impl Show for UiBody

    UiBody::output

    fn UiBody::output(self : UiBody, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    UiBody::to_repr

    automatically derived

    UiBody::to_string

    fn UiBody::to_string(self : UiBody) -> String

    UiChange

    pub(all) enum UiChange {
    Resource(change~ : UiResourceChange)
    Interaction(change~ : UiInteractionChange)
    } derive(Eq,
    Debug
    )

    One change of the ordered push feed.

    UiChange::equal

    fn UiChange::equal(UiChange, UiChange) -> Bool
    automatically derived

    UiChange::not_equal

    fn UiChange::not_equal(x : UiChange, y : UiChange) -> Bool
    automatically derived

    UiChange::to_repr

    automatically derived

    UiChanges

    pub(all) struct UiChanges {
    cursor : UiCursor
    changes : Array[UiResourceChange]
    } derive(Eq,
    Debug
    )

    Changes accepted strictly after the supplied cursor, with the cursor to continue from.

    UiChanges::equal

    fn UiChanges::equal(UiChanges, UiChanges) -> Bool
    automatically derived

    UiChanges::not_equal

    fn UiChanges::not_equal(x : UiChanges, y : UiChanges) -> Bool
    automatically derived

    UiChanges::to_repr

    automatically derived

    UiCursor

    pub(all) struct UiCursor {
    generation : Int
    seq : Int
    } derive(Eq,
    Debug
    )

    Position in the resource change feed.

    UiCursor::equal

    fn UiCursor::equal(UiCursor, UiCursor) -> Bool
    automatically derived

    UiCursor::not_equal

    fn UiCursor::not_equal(x : UiCursor, y : UiCursor) -> Bool
    automatically derived

    UiCursor::to_repr

    automatically derived

    UiDescriptor

    pub(all) struct UiDescriptor {
    autocomplete_sources : Array[AutocompleteSource]
    } derive(
    Debug
    )

    Collected at composition time: the host aggregates every UiPort's descriptors to know which autocomplete triggers to honor.

    UiDescriptor::empty

    fn UiDescriptor::empty() -> UiDescriptor

    Empty descriptor used by UIs that contribute no autocomplete sources.

    UiDescriptor::to_repr

    automatically derived

    UiEntry

    pub(all) struct UiEntry {
    key : String
    value : String
    color : String?
    } derive(Eq,
    Debug
    )

    One keyed entry of an Entries body. color carries a semantic role name from the host-negotiated vocabulary, never a raw color value.

    UiEntry::equal

    fn UiEntry::equal(UiEntry, UiEntry) -> Bool
    automatically derived

    UiEntry::not_equal

    fn UiEntry::not_equal(x : UiEntry, y : UiEntry) -> Bool
    automatically derived

    UiEntry::to_repr

    automatically derived

    UiFeedBatch

    pub(all) struct UiFeedBatch {
    cursor : UiCursor
    change : UiChange
    } derive(Eq,
    Debug
    )

    One delivered change plus the cursor of its own family.

    UiFeedBatch::equal

    fn UiFeedBatch::equal(UiFeedBatch, UiFeedBatch) -> Bool
    automatically derived

    UiFeedBatch::not_equal

    fn UiFeedBatch::not_equal(x : UiFeedBatch, y : UiFeedBatch) -> Bool
    automatically derived

    UiFeedBatch::to_repr

    automatically derived

    UiHint

    pub(all) enum UiHint {
    RefreshModelList
    RefreshSettings
    ClosePanel
    Toast
    None
    } derive(Eq,
    Debug
    )

    Hint to a panel consumer about what UI action to take after invoke. Slash consumers ignore this. Fixed enum + None fallback; ext long-tail needs go through CommandDef.metadata.

    UiHint::equal

    fn UiHint::equal(UiHint, UiHint) -> Bool
    automatically derived

    UiHint::not_equal

    fn UiHint::not_equal(x : UiHint, y : UiHint) -> Bool
    automatically derived

    UiHint::to_repr

    automatically derived

    UiHost

    pub struct UiHost {
    // private fields
    }

    Host observation, interaction and action handle, owned by the Agent.

    UiHost::answer

    Answer one pending interaction. The first valid answer settles it; the same value again replays the stored receipt, a different value is Conflict, and a question that already ended is AlreadySettled.

    UiHost::changes_since

    fn UiHost::changes_since(self : UiHost, cursor~ : UiCursor) -> Result[UiChanges, UiResourceError]

    Changes accepted after cursor. The caller must treat SnapshotRequired as "re-read snapshot", never as "nothing changed".

    UiHost::connect

    fn UiHost::connect(self : UiHost, capabilities~ : UiHostCapabilities) -> Result[UiHostConnection, UiInteractionError]

    Attach an explicit host lease with the capabilities this host declares. A subscription is observation only; only a connection whose interactions include the question's body kind keeps a blocking wait blocked. Detaching releases the lease and wakes waiters that lost their last matching host.

    UiHost::dismiss

    fn UiHost::dismiss(self : UiHost, interaction~ : UiInteractionRef, reason? : String) -> Result[UiInteractionOutcome, UiInteractionError]

    Dismiss one pending interaction: the user closed the prompt without choosing; the owner's waiter resumes with Dismissed. Re-dismissing a settled question is AlreadySettled.

    UiHost::dispatch

    async fn UiHost::dispatch(self : UiHost, request~ : UiActionRequest) -> Result[UiActionResult, UiResourceError] noraise

    Route one action to the resource's owner. Validation happens before the owner handler is awaited; a duplicate request id replays the stored receipt instead of running the handler twice.

    UiHost::from_callbacks

    Framework construction hook. Hosts obtain the value from the Agent.

    UiHost::interactions_since

    fn UiHost::interactions_since(self : UiHost, cursor~ : UiCursor) -> Result[UiInteractionChanges, UiResourceError]

    Interaction changes accepted after cursor. Same window and generation rules as changes_since, on the interaction feed.

    UiHost::snapshot

    fn UiHost::snapshot(self : UiHost) -> Result[UiBaseline, UiResourceError]

    Read the current baseline. Cheap, side-effect free and repeatable.

    UiHost::subscribe

    fn UiHost::subscribe(self : UiHost, listener~ : (UiFeedBatch) -> Result[Unit, String], on_failure~ : (UiListenerFailure) -> Unit) -> Result[UiObservation, UiResourceError]

    Subscribe to every change accepted from now on. The returned baseline already contains everything committed before the subscription; the listener receives everything after it, in commit order, synchronously inside the accepting mutation. Returning Err(detail) keeps the change accepted, calls on_failure once and drops the subscription.

    UiHostCapabilities

    pub(all) struct UiHostCapabilities {
    resource_kinds : Array[UiResourceKind]
    fallback : Bool
    interactions : Array[UiInteractionKind]
    } derive(Eq,
    Debug
    )

    What one connected host promises to display and answer. An empty resource_kinds or interactions list means "none", never "all".

    UiHostCapabilities::equal

    automatically derived

    UiHostCapabilities::new

    fn UiHostCapabilities::new(resource_kinds? : Array[UiResourceKind], fallback? : Bool, interactions? : Array[UiInteractionKind]) -> UiHostCapabilities

    Construct a capability declaration.

    UiHostCapabilities::not_equal

    automatically derived

    UiHostCapabilities::to_repr

    automatically derived

    UiHostConnection

    pub struct UiHostConnection {
    // private fields
    }

    Explicit host lease. detach is idempotent; updating capabilities after detaching and answering through a detached lease are HostUnavailable. Once the Agent closed, every call is Closed.

    UiHostConnection::answer

    Answer one question through this lease. The question's body kind must still be declared by this connected host; otherwise the answer is refused with HostUnavailable.

    UiHostConnection::detach

    Release the lease. Idempotent: a second detach is Ok(()); pending questions stay pending for a later host.

    UiHostConnection::dismiss

    fn UiHostConnection::dismiss(self : UiHostConnection, interaction~ : UiInteractionRef, reason? : String) -> Result[UiInteractionOutcome, UiInteractionError]

    Dismiss one question through this lease, under the same online and capability checks as answer.

    UiHostConnection::from_callbacks

    fn UiHostConnection::from_callbacks(id~ : Int, is_connected~ : () -> Bool, update~ : (UiHostCapabilities) -> Result[Unit, UiInteractionError], detach~ : () -> Result[Unit, UiInteractionError], answer~ : (UiInteractionAnswerRequest) -> Result[UiInteractionAnswerReceipt, UiInteractionError], dismiss~ : (UiInteractionRef, String) -> Result[UiInteractionOutcome, UiInteractionError]) -> UiHostConnection

    Framework construction hook. Hosts obtain the value from UiHost::connect.

    UiHostConnection::id

    fn UiHostConnection::id(self : UiHostConnection) -> Int

    Connection id, as reported by UiHostConnectionSupport.

    UiHostConnection::is_connected

    fn UiHostConnection::is_connected(self : UiHostConnection) -> Bool

    False after detach, after the Agent closed, or for an unknown lease.

    UiHostConnection::update

    fn UiHostConnection::update(self : UiHostConnection, capabilities~ : UiHostCapabilities) -> Result[Unit, UiInteractionError]

    Replace this host's capability declaration; visible to the next matching decision and to blocked waiters.

    UiHostConnectionSupport

    pub(all) struct UiHostConnectionSupport {
    connection : Int
    support : UiHostSupport
    } derive(Eq,
    Debug
    )

    One host's support answer, per connection.

    UiHostConnectionSupport::equal

    automatically derived

    UiHostConnectionSupport::not_equal

    automatically derived

    UiHostConnectionSupport::to_repr

    automatically derived

    UiHostSupport

    pub(all) enum UiHostSupport {
    Native
    Fallback
    Unsupported
    } derive(Eq,
    Debug
    )

    How one connected host relates to one resource kind.

    UiHostSupport::equal

    automatically derived

    UiHostSupport::not_equal

    fn UiHostSupport::not_equal(x : UiHostSupport, y : UiHostSupport) -> Bool
    automatically derived

    UiHostSupport::to_repr

    automatically derived

    UiInteractionAnswer

    pub(all) enum UiInteractionAnswer {
    Text(String)
    Yes
    No
    Choice(Int)
    } derive(Eq,
    Debug
    )

    The value the host answered with.

    UiInteractionAnswer::equal

    automatically derived

    UiInteractionAnswer::not_equal

    automatically derived

    UiInteractionAnswer::output

    fn UiInteractionAnswer::output(self : UiInteractionAnswer, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    UiInteractionAnswer::to_repr

    automatically derived

    UiInteractionAnswer::to_string

    fn UiInteractionAnswer::to_string(self : UiInteractionAnswer) -> String

    UiInteractionAnswerReceipt

    pub(all) struct UiInteractionAnswerReceipt {
    interaction : UiInteractionRef
    answer : UiInteractionAnswer
    replayed : Bool
    } derive(Eq,
    Debug
    )

    Receipt of an accepted answer.

    UiInteractionAnswerReceipt::equal

    automatically derived

    UiInteractionAnswerReceipt::not_equal

    automatically derived

    UiInteractionAnswerReceipt::to_repr

    automatically derived

    UiInteractionAnswerRequest

    pub(all) struct UiInteractionAnswerRequest {
    interaction : UiInteractionRef
    answer : UiInteractionAnswer
    } derive(Eq,
    Debug
    )

    Host-side intent to answer one pending question.

    UiInteractionAnswerRequest::equal

    automatically derived

    UiInteractionAnswerRequest::not_equal

    automatically derived

    UiInteractionAnswerRequest::to_repr

    automatically derived

    UiInteractionBody

    pub(all) enum UiInteractionBody {
    FreeText(default~ : String?)
    Confirmation
    Choice(options~ : Array[String], default~ : Int?)
    } derive(Eq,
    Debug
    )

    What the user is allowed to answer.

    UiInteractionBody::equal

    automatically derived

    UiInteractionBody::kind

    The capability category of a body.

    UiInteractionBody::not_equal

    fn UiInteractionBody::not_equal(x : UiInteractionBody, y : UiInteractionBody) -> Bool
    automatically derived

    UiInteractionBody::to_repr

    automatically derived

    UiInteractionChange

    pub(all) enum UiInteractionChange {
    Opened(snapshot~ : UiInteractionSnapshot)
    Settled(owner~ : String, request_id~ : String, outcome~ : UiInteractionOutcome)
    } derive(Eq,
    Debug
    )

    One lifecycle change of the interaction feed.

    UiInteractionChange::equal

    automatically derived

    UiInteractionChange::not_equal

    automatically derived

    UiInteractionChange::to_repr

    automatically derived

    UiInteractionChanges

    pub(all) struct UiInteractionChanges {
    cursor : UiCursor
    changes : Array[UiInteractionChange]
    } derive(Eq,
    Debug
    )

    Interaction changes accepted after the supplied interaction cursor.

    UiInteractionChanges::equal

    automatically derived

    UiInteractionChanges::not_equal

    automatically derived

    UiInteractionChanges::to_repr

    automatically derived

    UiInteractionError

    pub(all) enum UiInteractionError {
    Closed
    NotFound(owner~ : String, request_id~ : String)
    Duplicate(request_id~ : String)
    InvalidInput(reason~ : String)
    InvalidAnswer(reason~ : String)
    AlreadySettled(outcome~ : UiInteractionOutcome)
    Conflict(reason~ : String)
    PendingFull(limit~ : Int)
    HostUnavailable(reason~ : String)
    ConnectionsFull(limit~ : Int)
    Dismissed(reason~ : String)
    Withdrawn
    } derive(Eq,
    Debug
    )

    Explicit failures of the interaction protocol.

    UiInteractionError::equal

    automatically derived

    UiInteractionError::not_equal

    automatically derived

    UiInteractionError::output

    fn UiInteractionError::output(self : UiInteractionError, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    UiInteractionError::to_repr

    automatically derived

    UiInteractionError::to_string

    fn UiInteractionError::to_string(self : UiInteractionError) -> String

    UiInteractionKind

    pub(all) enum UiInteractionKind {
    TextInput
    YesNo
    SingleChoice
    } derive(Eq,
    Debug
    )

    Coarse body category a connected host can answer. A host declares these in UiHostCapabilities; an empty list means it can answer nothing.

    UiInteractionKind::equal

    automatically derived

    UiInteractionKind::not_equal

    fn UiInteractionKind::not_equal(x : UiInteractionKind, y : UiInteractionKind) -> Bool
    automatically derived

    UiInteractionKind::to_repr

    automatically derived

    UiInteractionOutcome

    pub(all) enum UiInteractionOutcome {
    Answered(answer~ : UiInteractionAnswer)
    Dismissed(reason~ : String)
    Withdrawn
    WaitCancelled
    Closed
    } derive(Eq,
    Debug
    )

    Terminal state of one interaction. Every terminal path is named; none of them is a silent removal from the pending set.

    UiInteractionOutcome::equal

    automatically derived

    UiInteractionOutcome::not_equal

    automatically derived

    UiInteractionOutcome::output

    fn UiInteractionOutcome::output(self : UiInteractionOutcome, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    UiInteractionOutcome::to_repr

    automatically derived

    UiInteractionOutcome::to_string

    fn UiInteractionOutcome::to_string(self : UiInteractionOutcome) -> String

    UiInteractionRef

    pub(all) struct UiInteractionRef {
    owner : String
    request_id : String
    generation : Int
    } derive(Eq,
    Debug
    )

    Address of one interaction: owner-local id plus the runtime generation that issued it. A ref from a previous generation is never accepted.

    UiInteractionRef::equal

    automatically derived

    UiInteractionRef::not_equal

    fn UiInteractionRef::not_equal(x : UiInteractionRef, y : UiInteractionRef) -> Bool
    automatically derived

    UiInteractionRef::to_repr

    automatically derived

    UiInteractionRequest

    pub(all) struct UiInteractionRequest {
    request_id : String
    scope : UiResourceScope
    prompt : String
    body : UiInteractionBody
    title : String?
    } derive(Eq,
    Debug
    )

    Owner-supplied request to open one question.

    UiInteractionRequest::equal

    automatically derived

    UiInteractionRequest::new

    fn UiInteractionRequest::new(request_id~ : String, prompt~ : String, body~ : UiInteractionBody, scope? : UiResourceScope, title? : String) -> UiInteractionRequest

    Construct a request with AgentScope, no title and no pre-fill.

    UiInteractionRequest::not_equal

    automatically derived

    UiInteractionRequest::to_repr

    automatically derived

    UiInteractionSnapshot

    pub(all) struct UiInteractionSnapshot {
    interaction : UiInteractionRef
    scope : UiResourceScope
    prompt : String
    body : UiInteractionBody
    title : String?
    } derive(Eq,
    Debug
    )

    One pending question as the host reads it.

    UiInteractionSnapshot::equal

    automatically derived

    UiInteractionSnapshot::not_equal

    automatically derived

    UiInteractionSnapshot::to_repr

    automatically derived

    UiInteractions

    pub struct UiInteractions {
    // private fields
    }

    Owner-bound interaction capability delivered through CompositionView::ui_interactions.

    UiInteractions::ask

    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.

    UiInteractions::find

    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.

    UiInteractions::from_callbacks

    Framework construction hook. Omitting ask or find makes the corresponding calls report HostUnavailable.

    UiInteractions::open

    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.

    UiInteractions::owner

    fn UiInteractions::owner(self : UiInteractions) -> String

    The manifest id this capability is bound to.

    UiInteractions::wait

    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.

    UiInteractions::withdraw

    Withdraw one pending question. Returns Withdrawn on success; the host sees the same outcome on the feed and any waiting task resumes with Withdrawn.

    UiListenerFailure

    pub(all) struct UiListenerFailure {
    subscription : Int
    seq : Int
    detail : String
    } derive(Eq,
    Debug
    )

    Reported when a subscriber's own listener fails; the failing subscription is dropped and the host must subscribe again.

    UiListenerFailure::equal

    automatically derived

    UiListenerFailure::not_equal

    fn UiListenerFailure::not_equal(x : UiListenerFailure, y : UiListenerFailure) -> Bool
    automatically derived

    UiListenerFailure::to_repr

    automatically derived

    UiObservation

    pub(all) struct UiObservation {
    baseline : UiBaseline
    subscription : UiSubscription
    }

    The atomic handoff of a push subscription: the baseline cut plus the handle for everything accepted after it.

    UiRender

    pub(all) struct UiRender {
    slot : UiSlot
    key : String
    title : String?
    body : UiBody
    ttl_ms : Int?
    } derive(
    Debug
    )

    One render intent. Same key replaces a prior intent in the same UiSlot.
    impl Show for UiRender

    UiRender::output

    fn UiRender::output(self : UiRender, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    UiRender::to_repr

    automatically derived

    UiRender::to_string

    fn UiRender::to_string(self : UiRender) -> String

    UiRequest

    pub(all) enum UiRequest {
    Input(prompt~ : String, default~ : String?)
    Confirm(prompt~ : String)
    Select(prompt~ : String, options~ : Array[String], default~ : Int?)
    } derive(
    Debug
    )

    User interaction primitives. Hosts that lack a variant raise UiError::Unsupported.
    impl Show for UiRequest

    UiRequest::output

    fn UiRequest::output(self : UiRequest, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    UiRequest::to_repr

    automatically derived

    UiRequest::to_string

    fn UiRequest::to_string(self : UiRequest) -> String

    UiResourceBody

    pub(all) enum UiResourceBody {
    Text(String)
    Lines(Array[String])
    KeyValue(Array[(String, String)])
    Entries(Array[UiEntry])
    Progress(Double)
    Markdown(String)
    Custom(
    Json
    )
    } derive(Eq,
    Debug
    )

    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.

    UiResourceBody::equal

    automatically derived

    UiResourceBody::not_equal

    fn UiResourceBody::not_equal(x : UiResourceBody, y : UiResourceBody) -> Bool
    automatically derived

    UiResourceBody::to_repr

    automatically derived

    UiResourceChange

    pub(all) enum UiResourceChange {
    Published(snapshot~ : UiResourceSnapshot)
    Replaced(snapshot~ : UiResourceSnapshot)
    Withdrawn(owner~ : String, key~ : String, revision~ : Int)
    } derive(Eq,
    Debug
    )

    Lifecycle change of one resource in the host feed.

    UiResourceChange::equal

    automatically derived

    UiResourceChange::not_equal

    fn UiResourceChange::not_equal(x : UiResourceChange, y : UiResourceChange) -> Bool
    automatically derived

    UiResourceChange::to_repr

    automatically derived

    UiResourceDraft

    pub(all) struct UiResourceDraft {
    key : String
    kind : UiResourceKind
    scope : UiResourceScope
    lifetime : UiResourceLifetime
    title : String?
    body : UiResourceBody
    actions : Array[UiActionSpec]
    } derive(Eq,
    Debug
    )

    Full replacement payload for publish / replace.

    UiResourceDraft::equal

    automatically derived

    UiResourceDraft::new

    fn UiResourceDraft::new(key~ : String, kind~ : UiResourceKind, body~ : UiResourceBody, scope? : UiResourceScope, lifetime? : UiResourceLifetime, title? : String, actions? : Array[UiActionSpec]) -> UiResourceDraft

    Construct a draft with the common defaults: AgentScope, OwnerBound, no title and no actions.

    UiResourceDraft::not_equal

    fn UiResourceDraft::not_equal(x : UiResourceDraft, y : UiResourceDraft) -> Bool
    automatically derived

    UiResourceDraft::to_repr

    automatically derived

    UiResourceError

    pub(all) enum UiResourceError {
    Closed
    Unsupported(feature~ : String)
    NotFound(owner~ : String, key~ : String)
    StaleRevision(expected~ : Int, actual~ : Int)
    InvalidInput(reason~ : String)
    Conflict(reason~ : String)
    InProgress(request_id~ : String)
    HandlerFailed(detail~ : String)
    SnapshotRequired(reason~ : String)
    } derive(Eq,
    Debug
    )

    Explicit, non-silent outcomes of the resource protocol.

    UiResourceError::equal

    automatically derived

    UiResourceError::not_equal

    fn UiResourceError::not_equal(x : UiResourceError, y : UiResourceError) -> Bool
    automatically derived

    UiResourceError::output

    fn UiResourceError::output(self : UiResourceError, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    UiResourceError::to_repr

    automatically derived

    UiResourceError::to_string

    fn UiResourceError::to_string(self : UiResourceError) -> String

    UiResourceKind

    pub(all) struct UiResourceKind {
    namespace_ : String
    name : String
    schema_version : Int
    } derive(Eq,
    Debug
    )

    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.

    UiResourceKind::custom

    fn UiResourceKind::custom(namespace_~ : String, name~ : String, schema_version? : Int) -> UiResourceKind

    Construct a custom namespaced kind. schema_version must be positive.

    UiResourceKind::equal

    automatically derived

    UiResourceKind::not_equal

    fn UiResourceKind::not_equal(x : UiResourceKind, y : UiResourceKind) -> Bool
    automatically derived

    UiResourceKind::standard

    fn UiResourceKind::standard(name~ : String) -> UiResourceKind

    Construct a framework (posoco) kind.

    UiResourceKind::to_repr

    automatically derived

    UiResourceLifetime

    pub(all) enum UiResourceLifetime {
    OwnerBound
    SessionBound
    OperationBound
    } derive(Eq,
    Debug
    )

    Reclamation promise of a published resource.

    UiResourceLifetime::equal

    automatically derived

    UiResourceLifetime::not_equal

    automatically derived

    UiResourceLifetime::to_repr

    automatically derived

    UiResourceRef

    pub(all) struct UiResourceRef {
    owner : String
    key : String
    generation : Int
    } derive(Eq,
    Debug
    )

    Owner-local address of one resource, bound to the runtime generation that issued it. A ref from a previous runtime generation is never accepted.

    UiResourceRef::equal

    automatically derived

    UiResourceRef::not_equal

    fn UiResourceRef::not_equal(x : UiResourceRef, y : UiResourceRef) -> Bool
    automatically derived

    UiResourceRef::to_repr

    automatically derived

    UiResourceScope

    pub(all) enum UiResourceScope {
    AgentScope
    SessionScope(id~ : String)
    OperationScope(id~ : String)
    ToolCallScope(id~ : String)
    } derive(Eq,
    Debug
    )

    Where a resource belongs.

    UiResourceScope::equal

    automatically derived

    UiResourceScope::not_equal

    fn UiResourceScope::not_equal(x : UiResourceScope, y : UiResourceScope) -> Bool
    automatically derived

    UiResourceScope::to_repr

    automatically derived

    UiResourceSnapshot

    pub(all) struct UiResourceSnapshot {
    resource : UiResourceRef
    revision : Int
    kind : UiResourceKind
    scope : UiResourceScope
    lifetime : UiResourceLifetime
    title : String?
    body : UiResourceBody
    actions : Array[UiActionSpec]
    } derive(Eq,
    Debug
    )

    Immutable copy of one accepted resource revision, as read through the host feed. Replacing a resource bumps revision and keeps the same ref.

    UiResourceSnapshot::equal

    automatically derived

    UiResourceSnapshot::not_equal

    automatically derived

    UiResourceSnapshot::to_repr

    automatically derived

    UiResources

    pub struct UiResources {
    // private fields
    }

    Owner-bound capability delivered through CompositionView::ui_resources.

    UiResources::from_callbacks

    fn UiResources::from_callbacks(owner~ : String, publish~ : (UiResourceDraft) -> Result[UiResourceSnapshot, UiResourceError], replace~ : (UiResourceDraft, Int) -> Result[UiResourceSnapshot, UiResourceError], remove~ : (UiResourceRef) -> Result[Int, UiResourceError], set_action_handler~ : (async (UiActionInvocation) -> Result[Unit, String]) -> Result[Unit, UiResourceError], operation? : () -> Result[UiResources, UiResourceError], host_support? : (UiResourceRef) -> Result[Array[UiHostConnectionSupport], UiResourceError]) -> UiResources

    Framework construction hook. Omitting operation or host_support makes the corresponding calls report Unsupported.

    UiResources::host_support

    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.

    UiResources::operation

    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.

    UiResources::owner

    fn UiResources::owner(self : UiResources) -> String

    The manifest id this capability is bound to.

    UiResources::publish

    Create the resource, or fully replace it when this owner already published the same key. Returns the accepted snapshot (with its new revision).

    UiResources::remove

    fn UiResources::remove(self : UiResources, resource~ : UiResourceRef) -> Result[Int, UiResourceError]

    Withdraw this owner's resource. Returns the last live revision; repeating the withdrawal is NotFound.

    UiResources::replace

    fn UiResources::replace(self : UiResources, draft~ : UiResourceDraft, expected~ : Int) -> Result[UiResourceSnapshot, UiResourceError]

    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.

    UiResources::set_action_handler

    fn UiResources::set_action_handler(self : UiResources, handler~ : async (UiActionInvocation) -> Result[Unit, String]) -> Result[Unit, UiResourceError]

    Install the owner's action handler. Registering again replaces the previous handler; after Agent::shutdown registration is rejected with Closed.

    UiResponse

    pub(all) enum UiResponse {
    Text(String)
    Yes
    No
    Selected(Int)
    Cancelled
    } derive(Eq,
    Debug
    )

    Response to a UiRequest. Cancelled = user dismissed; no UI = UiError::Unsupported.
    impl Show for UiResponse

    UiResponse::equal

    fn UiResponse::equal(UiResponse, UiResponse) -> Bool
    automatically derived

    UiResponse::not_equal

    fn UiResponse::not_equal(x : UiResponse, y : UiResponse) -> Bool
    automatically derived

    UiResponse::output

    fn UiResponse::output(self : UiResponse, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    UiResponse::to_repr

    automatically derived

    UiResponse::to_string

    fn UiResponse::to_string(self : UiResponse) -> String

    UiSlot

    pub(all) enum UiSlot {
    Status
    Notice
    Widget
    } derive(Eq,
    Debug
    )

    Where a render intent lands: Status (single-line bar), Notice (transient toast), Widget (persistent region).
    impl Show for UiSlot

    UiSlot::equal

    fn UiSlot::equal(UiSlot, UiSlot) -> Bool
    automatically derived

    UiSlot::not_equal

    fn UiSlot::not_equal(x : UiSlot, y : UiSlot) -> Bool
    automatically derived

    UiSlot::output

    fn UiSlot::output(self : UiSlot, logger : &Logger) -> Unit

    Default implementation for Show::output, uses Show::to_string.

    UiSlot::to_repr

    automatically derived

    UiSlot::to_string

    fn UiSlot::to_string(self : UiSlot) -> String

    UiSubscription

    pub struct UiSubscription {
    // private fields
    }

    Live push subscription delivering changes in commit order.

    UiSubscription::from_callbacks

    fn UiSubscription::from_callbacks(id~ : Int, is_active~ : () -> Bool, unsubscribe~ : () -> Unit) -> UiSubscription

    Framework construction hook. Hosts obtain the value from the Agent.

    UiSubscription::id

    fn UiSubscription::id(self : UiSubscription) -> Int

    Subscription id, as reported by UiListenerFailure.

    UiSubscription::is_active

    fn UiSubscription::is_active(self : UiSubscription) -> Bool

    False once unsubscribed, dropped after a listener failure, or closed by Agent::shutdown.

    UiSubscription::unsubscribe

    fn UiSubscription::unsubscribe(self : UiSubscription) -> Unit

    Stop delivery. Idempotent, and safe to call from inside the listener itself; no change is delivered after it returns.

    WakeupError

    pub(all) enum WakeupError {
    ScopeInactive
    TagInvalid(reason~ : String)
    InvalidSession(reason~ : String)
    PendingFull(session~ : String, limit~ : Int)
    } derive(Eq,
    Debug
    )

    Admission failures are explicit so an extension cannot mistake a closed scope, a malformed tag, or an invalid session for accepted work.

    WakeupError::equal

    fn WakeupError::equal(WakeupError, WakeupError) -> Bool
    automatically derived

    WakeupError::not_equal

    fn WakeupError::not_equal(x : WakeupError, y : WakeupError) -> Bool
    automatically derived

    WakeupError::to_repr

    automatically derived

    WakeupPort

    pub struct WakeupPort {
    // private fields
    }

    Queue a wakeup for the session. At an eligible step boundary in a turn for that session, pending wakeups can enter the turn as separate input messages. A ticket is satisfied only after the journal commits the boundary that applies its message. wakeup_satisfied is scoped to the actual turn and reports delivery=step and the operation id. If the Agent is idle, the pump can instead start an ordinary turn for the ticket. Wakeup alone can extend a turn at most 64 times; outstanding tickets remain eligible for the idle pump.

    Requests are synchronous and never await, including from task bodies, observer callbacks, and hook tails. The session must be the Agent's currently bound active window session (set by Agent::set_active_session). Pending tickets are dropped when that binding changes and do not survive process exit. Requests for a pending (session, tag) return the same ticket and replace its note without another wakeup_requested event. A request made after a step snapshot remains pending even if the earlier message is committed.

    WakeupPort::from_request

    fn WakeupPort::from_request(request~ : (String, String, String) -> Result[WakeupTicket, WakeupError]) -> WakeupPort

    Framework construction hook. Product extensions obtain the value through CompositionView::wakeup and do not need this constructor.

    WakeupPort::request

    fn WakeupPort::request(self : WakeupPort, session~ : String, tag~ : String, note? : String) -> Result[WakeupTicket, WakeupError]

    WakeupTicket

    pub(all) struct WakeupTicket {
    id : String
    session : String
    tag : String
    enqueued_at : Int64
    } derive(Eq,
    Debug
    )

    Opaque admission ticket. id is stable per pending (session, tag) entry; a coalesced re-request returns the same ticket. enqueued_at is an observation timestamp read from the async runtime's timer clock, for display and diagnostics only — it is never part of ticket identity or correctness, and carries no monotonicity guarantee.

    WakeupTicket::equal

    automatically derived

    WakeupTicket::not_equal

    fn WakeupTicket::not_equal(x : WakeupTicket, y : WakeupTicket) -> Bool
    automatically derived

    WakeupTicket::to_repr

    automatically derived