Package net.thevpc.naru.api.registry

Interface NaruSessionExtension

All Superinterfaces:
NComponent
public interface NaruSessionExtension extends NComponent
A session-scoped feature that the core knows nothing about.

Exactly one instance is created per session, so an implementation may keep mutable per-session state in instance fields. That single-instance guarantee is the reason prompt contribution and durable state live on the same interface: a feature that both renders a prompt and owns persisted state needs the same object to answer both, and the registry creates providers once per lookup otherwise.

A session extension is optional. Removing its jar from the classpath removes the feature, with no core change and no dangling references.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
    Called when the session is terminated.
    default List<NaruMessage>
    contribute(NaruTask task)
    Messages to splice into the task's context.
    default boolean
    isRelevant(NaruTask task)
    Whether this extension has anything to say to this task.
    default NOptional<NElement>
    load(NaruSession session, NPath file)
    Restores state from file, which may not exist.
    String
    name()
    Stable identifier.
    default void
    open(NaruSession session)
    Called after #load(NaruSession) and before any task runs.
    default int
    order()
    Ascending contribution order.
    default NElement
    save(NaruSession session)
    Snapshots state for persistence.
    default NaruSource
    source()
    The source stamped on contributed messages, so /context and /stats can attribute them.
    default Set<NaruSource>
    sources()
    The NaruSources that must be enabled on a task for its contribution to be considered.

  • Method Details

    • name

      String name()
      Stable identifier. Used as the source name for contributed messages and as the basename of this extension's state file, so it must be a safe file name and must not change between releases without a migration.

    • order

      default int order()
      Ascending contribution order. Built-in contributors sort first; extensions should use 100 or more so their content appears after core content.

    • sources

      default Set<NaruSource> sources()
      The NaruSources that must be enabled on a task for its contribution to be considered. Defaults to NaruSource.SYSTEM, matching how a feature's instructions are treated as system material.

    • source

      default NaruSource source()
      The source stamped on contributed messages, so /context and /stats can attribute them. Defaults to NaruSource.SYSTEM.

    • isRelevant

      default boolean isRelevant(NaruTask task)
      Whether this extension has anything to say to this task. Called before contribute(NaruTask) so an inactive feature costs one predicate call.

    • contribute

      default List<NaruMessage> contribute(NaruTask task)
      Messages to splice into the task's context. Evaluated on every call, so an implementation must read current state rather than cache it. The returned messages have their source applied by the core; a message that already carries a source name keeps it, and one that does not is attributed to name().

    • load

      default NOptional<NElement> load(NaruSession session, NPath file)
      Restores state from file, which may not exist. Returning NOptional#empty() leaves the extension at its initial state. Called once per session load, before open(NaruSession).

    • save

      default NElement save(NaruSession session)
      Snapshots state for persistence. Returning null writes nothing, and causes any stale state file to be deleted.

      This is called far more often than a user-initiated save (session env changes trigger a snapshot), so it must be cheap and idempotent.

    • open

      default void open(NaruSession session)
      Called after #load(NaruSession) and before any task runs.

    • close

      default void close()
      Called when the session is terminated.